<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Chapter 27 Connectors and APIs</title>
<link rel="stylesheet" href="mvl.css" type="text/css" />
<meta name="generator" content="DocBook XSL Stylesheets + chunker.py v1.9.2" />
<link rel="start" href="index.html" title="{book-title}" />
<link rel="up" href="" title="" />
<link rel="prev" href="sys-schema.html" title="Chapter 26 MySQL sys Schema" />
<link rel="next" href="extending-mysql.html" title="Chapter 28 Extending MySQL" />
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Chapter 27 Connectors and APIs</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="sys-schema.html">Prev</a> </td>
<th width="60%" align="center"></th>
<td width="20%" align="right"> <a accesskey="n" href="extending-mysql.html">Next</a></td>
</tr>
</table>
<hr>
</div>
<div class="chapter">
<div class="titlepage">
<div>
<div>
<h1 class="title"><a name="connectors-apis"></a>Chapter 27 Connectors and APIs</h1>

</div>

</div>

</div>
<div class="toc">
<p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="connectors-apis.html#connector-c-info">27.1 MySQL Connector/C</a></span></dt><dt><span class="section"><a href="connectors-apis.html#connector-cpp-info">27.2 MySQL Connector/C++</a></span></dt><dt><span class="section"><a href="connectors-apis.html#connector-j-info">27.3 MySQL Connector/J</a></span></dt><dt><span class="section"><a href="connectors-apis.html#connector-net-info">27.4 MySQL Connector/Net</a></span></dt><dt><span class="section"><a href="connectors-apis.html#connector-odbc-info">27.5 MySQL Connector/ODBC</a></span></dt><dt><span class="section"><a href="connectors-apis.html#connector-python-info">27.6 MySQL Connector/Python</a></span></dt><dt><span class="section"><a href="connectors-apis.html#libmysqld">27.7 libmysqld, the Embedded MySQL Server Library</a></span></dt><dd><dl><dt><span class="section"><a href="connectors-apis.html#libmysqld-compiling">27.7.1 Compiling Programs with libmysqld</a></span></dt><dt><span class="section"><a href="connectors-apis.html#libmysqld-restrictions">27.7.2 Restrictions When Using the Embedded MySQL Server</a></span></dt><dt><span class="section"><a href="connectors-apis.html#libmysqld-options">27.7.3 Options with the Embedded Server</a></span></dt><dt><span class="section"><a href="connectors-apis.html#libmysqld-example">27.7.4 Embedded Server Examples</a></span></dt></dl></dd><dt><span class="section"><a href="connectors-apis.html#c-api">27.8 MySQL C API</a></span></dt><dd><dl><dt><span class="section"><a href="connectors-apis.html#c-api-implementations">27.8.1 MySQL C API Implementations</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-multiple-installations">27.8.2 Simultaneous MySQL Server and Connector/C Installations</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-example-programs">27.8.3 Example C API Client Programs</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-building-running-clients">27.8.4 Building and Running C API Client Programs</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-data-structures">27.8.5 C API Data Structures</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-function-overview">27.8.6 C API Function Overview</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-functions">27.8.7 C API Function Descriptions</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-prepared-statements">27.8.8 C API Prepared Statements</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-prepared-statement-data-structures">27.8.9 C API Prepared Statement Data Structures</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-prepared-statement-function-overview">27.8.10 C API Prepared Statement Function Overview</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-prepared-statement-functions">27.8.11 C API Prepared Statement Function Descriptions</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-thread-functions">27.8.12 C API Threaded Function Descriptions</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-embedded-server-functions">27.8.13 C API Embedded Server Function Descriptions</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-plugin-functions">27.8.14 C API Client Plugin Functions</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-encrypted-connections">27.8.15 C API Encrypted Connection Support</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-multiple-queries">27.8.16 C API Multiple Statement Execution Support</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-prepared-statement-date-handling">27.8.17 C API Prepared Statement Handling of Date and Time Values</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-prepared-call-statements">27.8.18 C API Prepared CALL Statement Support</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-prepared-statement-problems">27.8.19 C API Prepared Statement Problems</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-auto-reconnect">27.8.20 C API Automatic Reconnection Control</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-common-issues">27.8.21 C API Common Issues</a></span></dt></dl></dd><dt><span class="section"><a href="connectors-apis.html#apis-php-info">27.9 MySQL PHP API</a></span></dt><dt><span class="section"><a href="connectors-apis.html#apis-perl">27.10 MySQL Perl API</a></span></dt><dt><span class="section"><a href="connectors-apis.html#apis-python">27.11 MySQL Python API</a></span></dt><dt><span class="section"><a href="connectors-apis.html#apis-ruby">27.12 MySQL Ruby APIs</a></span></dt><dd><dl><dt><span class="section"><a href="connectors-apis.html#apis-ruby-mysqlruby">27.12.1 The MySQL/Ruby API</a></span></dt><dt><span class="section"><a href="connectors-apis.html#apis-ruby-rubymysql">27.12.2 The Ruby/MySQL API</a></span></dt></dl></dd><dt><span class="section"><a href="connectors-apis.html#apis-tcl">27.13 MySQL Tcl API</a></span></dt><dt><span class="section"><a href="connectors-apis.html#apis-eiffel">27.14 MySQL Eiffel Wrapper</a></span></dt></dl>
</div>
<a class="indexterm" name="idm140710576980144"></a><a class="indexterm" name="idm140710576979072"></a><a class="indexterm" name="idm140710576978000"></a><a class="indexterm" name="idm140710576976928"></a><a class="indexterm" name="idm140710576975856"></a><a class="indexterm" name="idm140710576974784"></a><a class="indexterm" name="idm140710576973712"></a><a class="indexterm" name="idm140710576972640"></a><a class="indexterm" name="idm140710576971568"></a><a class="indexterm" name="idm140710576970496"></a><a class="indexterm" name="idm140710576969424"></a><a class="indexterm" name="idm140710576968352"></a><a class="indexterm" name="idm140710576967280"></a><a class="indexterm" name="idm140710576966208"></a><a class="indexterm" name="idm140710576964720"></a><a class="indexterm" name="idm140710576963232"></a><p>
    MySQL Connectors provide connectivity to the MySQL server for client
    programs. APIs provide low-level access to the MySQL protocol and
    MySQL resources. Both Connectors and the APIs enable you to connect
    and execute MySQL statements from another language or environment,
    including ODBC, Java (JDBC), Perl, Python, PHP, Ruby, and native C
    and embedded MySQL instances.
</p>
<h2><a name="idm140710576960944"></a>MySQL Connectors</h2>
<p>
    Oracle develops a number of connectors:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
        <a class="ulink" href="http://dev.mysql.com/doc/connector-c/en/" target="_top">Connector/C</a> is a standalone
        replacement for the MySQL Client Library
        (<code class="literal">libmysqlclient</code>), to be used for C
        applications.
      </p></li><li class="listitem"><p>
        <a class="ulink" href="http://dev.mysql.com/doc/connector-cpp/en/" target="_top">Connector/C++</a> enables C++
        applications to connect to MySQL.
      </p></li><li class="listitem"><p>
        <a class="ulink" href="http://dev.mysql.com/doc/connector-j/5.1/en/" target="_top">Connector/J</a> provides
        driver support for connecting to MySQL from Java applications
        using the standard Java Database Connectivity (JDBC) API.
      </p></li><li class="listitem"><p>
        <a class="ulink" href="http://dev.mysql.com/doc/connector-net/en/" target="_top">Connector/Net</a> enables
        developers to create .NET applications that connect to MySQL.
        Connector/Net implements a fully functional ADO.NET interface
        and provides support for use with ADO.NET aware tools.
        Applications that use Connector/Net can be written in any
        supported .NET language.
      </p><p>
        <a class="ulink" href="http://dev.mysql.com/doc/visual-studio/en/" target="_top">MySQL for Visual Studio</a> works with
        Connector/Net and Microsoft Visual Studio 2012, 2013, 2015, and
        2017. MySQL for Visual Studio provides access to MySQL objects and data from
        Visual Studio. As a Visual Studio package, it integrates
        directly into Server Explorer providing the ability to create
        new connections and work with MySQL database objects.
      </p></li><li class="listitem"><p>
        <a class="ulink" href="http://dev.mysql.com/doc/connector-odbc/en/" target="_top">Connector/ODBC</a> provides
        driver support for connecting to MySQL using the Open Database
        Connectivity (ODBC) API. Support is available for ODBC
        connectivity from Windows, Unix, and OS X platforms.
      </p></li><li class="listitem"><p>
        <a class="ulink" href="http://dev.mysql.com/doc/connector-python/en/" target="_top">Connector/Python</a>
        provides driver support for connecting to MySQL from Python
        applications using an API that is compliant with the
        <a class="ulink" href="http://www.python.org/dev/peps/pep-0249/" target="_top">Python DB
        API version 2.0</a>. No additional Python modules or MySQL
        client libraries are required.
</p></li></ul>
</div>
<h2><a name="idm140710576946352"></a>The MySQL C API</h2>
<p>
    For direct access to using MySQL natively within a C application,
    there are two methods:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
        The <a class="link" href="connectors-apis.html#c-api" title="27.8 MySQL C API">C API</a> provides low-level access
        to the MySQL client/server protocol through the
        <code class="literal">libmysqlclient</code> client library. This is the
        primary method used to connect to an instance of the MySQL
        server, and is used both by MySQL command-line clients and many
        of the MySQL Connectors and third-party APIs detailed here.
      </p><p>
        <code class="literal">libmysqlclient</code> is included in MySQL
        distributions and in Connector/C distributions.
      </p></li><li class="listitem"><p>
        <code class="literal">libmysqld</code> is an embedded MySQL server library
        that enables you to embed an instance of the MySQL server into
        your C applications.
      </p><p>
        <code class="literal">libmysqld</code> is included in MySQL distributions,
        but not in Connector/C distributions.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
          The <code class="literal">libmysqld</code> embedded server library is
          deprecated as of MySQL 5.7.19 and will be removed in MySQL
          8.0.
</p>
</div>
</li></ul>
</div>
<p>
    See also <a class="xref" href="connectors-apis.html#c-api-implementations" title="27.8.1 MySQL C API Implementations">Section 27.8.1, “MySQL C API Implementations”</a>.
  </p><p>
    To access MySQL from a C application, or to build an interface to
    MySQL for a language not supported by the Connectors or APIs in this
    chapter, the <a class="link" href="connectors-apis.html#c-api" title="27.8 MySQL C API">C API</a> is where to start. A
    number of programmer's utilities are available to help with the
    process; see <a class="xref" href="programs.html#programs-development" title="4.7 MySQL Program Development Utilities">Section 4.7, “MySQL Program Development Utilities”</a>.
</p>
<h2><a name="idm140710576932976"></a>Third-Party MySQL APIs</h2>
<p>
    The remaining APIs described in this chapter provide an interface to
    MySQL from specific application languages. These third-party
    solutions are not developed or supported by Oracle. Basic
    information on their usage and abilities is provided here for
    reference purposes only.
  </p><p>
    All the third-party language APIs are developed using one of two
    methods, using <code class="literal">libmysqlclient</code> or by implementing
    a <span class="firstterm">native driver</span>. The two
    solutions offer different benefits:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
        Using <span class="emphasis"><em><code class="literal">libmysqlclient</code></em></span>
        offers complete compatibility with MySQL because it uses the
        same libraries as the MySQL client applications. However, the
        feature set is limited to the implementation and interfaces
        exposed through <code class="literal">libmysqlclient</code> and the
        performance may be lower as data is copied between the native
        language, and the MySQL API components.
      </p></li><li class="listitem"><p>
        <span class="emphasis"><em>Native drivers</em></span> are an implementation of the
        MySQL network protocol entirely within the host language or
        environment. Native drivers are fast, as there is less copying
        of data between components, and they can offer advanced
        functionality not available through the standard MySQL API.
        Native drivers are also easier for end users to build and deploy
        because no copy of the MySQL client libraries is needed to build
        the native driver components.
</p></li></ul>
</div>
<p>
    <a class="xref" href="connectors-apis.html#connectors-apis-summary" title="Table 27.1 MySQL APIs and Interfaces">Table 27.1, “MySQL APIs and Interfaces”</a> lists many of the
    libraries and interfaces available for MySQL.

</p>
<div class="table">
<a name="connectors-apis-summary"></a><p class="title"><b>Table 27.1 MySQL APIs and Interfaces</b></p>
<div class="table-contents">
<table summary="Summary of MySQL APIs and interfaces showing the environment, API, type, and related notes."><col width="10%"><col width="35%"><col width="15%"><col width="40%"><thead><tr>
      <th scope="col">Environment</th>
      <th scope="col">API</th>
      <th scope="col">Type</th>
      <th scope="col">Notes</th>
    </tr></thead><tbody><tr>
      <td scope="row">Ada</td>
      <td>GNU Ada MySQL Bindings</td>
      <td><code class="literal">libmysqlclient</code></td>
      <td>See <a class="ulink" href="http://gnade.sourceforge.net/" target="_top">MySQL Bindings for GNU
        Ada</a></td>
    </tr><tr>
      <td scope="row">C</td>
      <td>C API</td>
      <td><code class="literal">libmysqlclient</code></td>
      <td>See <a class="xref" href="connectors-apis.html#c-api" title="27.8 MySQL C API">Section 27.8, “MySQL C API”</a>.</td>
    </tr><tr>
      <td scope="row">C</td>
      <td>Connector/C</td>
      <td>Replacement for <code class="literal">libmysqlclient</code></td>
      <td>See <a class="ulink" href="http://dev.mysql.com/doc/connector-c/en/" target="_top">MySQL Connector/C Developer Guide</a>.</td>
    </tr><tr>
      <td scope="row">C++</td>
      <td>Connector/C++</td>
      <td><code class="literal">libmysqlclient</code></td>
      <td>See <a class="ulink" href="http://dev.mysql.com/doc/connector-cpp/en/" target="_top">MySQL Connector/C++ Developer Guide</a>.</td>
    </tr><tr>
      <td scope="row"></td>
      <td>MySQL++</td>
      <td><code class="literal">libmysqlclient</code></td>
      <td>See <a class="ulink" href="http://tangentsoft.net/mysql++/doc/" target="_top">MySQL++
        website</a>.</td>
    </tr><tr>
      <td scope="row"></td>
      <td>MySQL wrapped</td>
      <td><code class="literal">libmysqlclient</code></td>
      <td>See <a class="ulink" href="http://www.alhem.net/project/mysql/" target="_top">MySQL
        wrapped</a>.</td>
    </tr><tr>
      <td scope="row">Cocoa</td>
      <td>MySQL-Cocoa</td>
      <td><code class="literal">libmysqlclient</code></td>
      <td>Compatible with the Objective-C Cocoa environment. See
        <a class="ulink" href="http://mysql-cocoa.sourceforge.net/" target="_top">http://mysql-cocoa.sourceforge.net/</a></td>
    </tr><tr>
      <td scope="row">D</td>
      <td>MySQL for D</td>
      <td><code class="literal">libmysqlclient</code></td>
      <td>See <a class="ulink" href="http://www.steinmole.de/d/" target="_top">MySQL for D</a>.</td>
    </tr><tr>
      <td scope="row">Eiffel</td>
      <td>Eiffel MySQL</td>
      <td><code class="literal">libmysqlclient</code></td>
      <td>See <a class="xref" href="connectors-apis.html#apis-eiffel" title="27.14 MySQL Eiffel Wrapper">Section 27.14, “MySQL Eiffel Wrapper”</a>.</td>
    </tr><tr>
      <td scope="row">Erlang</td>
      <td><code class="literal">erlang-mysql-driver</code></td>
      <td><code class="literal">libmysqlclient</code></td>
      <td>See
        <a class="ulink" href="http://code.google.com/p/erlang-mysql-driver/" target="_top"><code class="literal">erlang-mysql-driver</code>.</a></td>
    </tr><tr>
      <td scope="row">Haskell</td>
      <td>Haskell MySQL Bindings</td>
      <td>Native Driver</td>
      <td>See <a class="ulink" href="http://www.serpentine.com/blog/software/mysql/" target="_top">Brian
        O'Sullivan's pure Haskell MySQL bindings</a>.</td>
    </tr><tr>
      <td scope="row"></td>
      <td><code class="literal">hsql-mysql</code></td>
      <td><code class="literal">libmysqlclient</code></td>
      <td>See
        <a class="ulink" href="http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hsql-mysql-1.7" target="_top">MySQL
        driver for Haskell</a>.</td>
    </tr><tr>
      <td scope="row">Java/JDBC</td>
      <td>Connector/J</td>
      <td>Native Driver</td>
      <td>See <a class="ulink" href="http://dev.mysql.com/doc/connector-j/5.1/en/" target="_top">MySQL Connector/J 5.1 Developer Guide</a>.</td>
    </tr><tr>
      <td scope="row">Kaya</td>
      <td>MyDB</td>
      <td><code class="literal">libmysqlclient</code></td>
      <td>See <a class="ulink" href="http://kayalang.org/library/latest/MyDB" target="_top">MyDB</a>.</td>
    </tr><tr>
      <td scope="row">Lua</td>
      <td>LuaSQL</td>
      <td><code class="literal">libmysqlclient</code></td>
      <td>See
        <a class="ulink" href="http://keplerproject.github.io/luasql/doc/us/" target="_top">LuaSQL</a>.</td>
    </tr><tr>
      <td scope="row">.NET/Mono</td>
      <td>Connector/Net</td>
      <td>Native Driver</td>
      <td>See <a class="ulink" href="http://dev.mysql.com/doc/connector-net/en/" target="_top">MySQL Connector/Net Developer Guide</a>.</td>
    </tr><tr>
      <td scope="row">Objective Caml</td>
      <td>OBjective Caml MySQL Bindings</td>
      <td><code class="literal">libmysqlclient</code></td>
      <td>See <a class="ulink" href="http://raevnos.pennmush.org/code/ocaml-mysql/" target="_top">MySQL
        Bindings for Objective Caml</a>.</td>
    </tr><tr>
      <td scope="row">Octave</td>
      <td>Database bindings for GNU Octave</td>
      <td><code class="literal">libmysqlclient</code></td>
      <td>See
        <a class="ulink" href="http://octave.sourceforge.net/database/index.html" target="_top">Database
        bindings for GNU Octave</a>.</td>
    </tr><tr>
      <td scope="row">ODBC</td>
      <td>Connector/ODBC</td>
      <td><code class="literal">libmysqlclient</code></td>
      <td>See <a class="ulink" href="http://dev.mysql.com/doc/connector-odbc/en/" target="_top">MySQL Connector/ODBC Developer Guide</a>.</td>
    </tr><tr>
      <td scope="row">Perl</td>
      <td><code class="literal">DBI</code>/<code class="literal">DBD::mysql</code></td>
      <td><code class="literal">libmysqlclient</code></td>
      <td>See <a class="xref" href="connectors-apis.html#apis-perl" title="27.10 MySQL Perl API">Section 27.10, “MySQL Perl API”</a>.</td>
    </tr><tr>
      <td scope="row"></td>
      <td><code class="literal">Net::MySQL</code></td>
      <td>Native Driver</td>
      <td>See
        <a class="ulink" href="http://search.cpan.org/dist/Net-MySQL/MySQL.pm" target="_top"><code class="literal">Net::MySQL</code></a>
        at CPAN</td>
    </tr><tr>
      <td scope="row">PHP</td>
      <td><code class="literal">mysql</code>, <code class="literal">ext/mysql</code> interface
        (deprecated)</td>
      <td><code class="literal">libmysqlclient</code></td>
      <td>See <a class="ulink" href="http://dev.mysql.com/doc/apis-php/en/apis-php-mysql.html" target="_top">Original MySQL API</a>.</td>
    </tr><tr>
      <td scope="row"></td>
      <td><code class="literal">mysqli</code>, <code class="literal">ext/mysqli</code> interface</td>
      <td><code class="literal">libmysqlclient</code></td>
      <td>See <a class="ulink" href="http://dev.mysql.com/doc/apis-php/en/apis-php-mysqli.html" target="_top">MySQL Improved Extension</a>.</td>
    </tr><tr>
      <td scope="row"></td>
      <td><code class="literal">PDO_MYSQL</code></td>
      <td><code class="literal">libmysqlclient</code></td>
      <td>See <a class="ulink" href="http://dev.mysql.com/doc/apis-php/en/apis-php-pdo-mysql.html" target="_top">MySQL Functions (PDO_MYSQL)</a>.</td>
    </tr><tr>
      <td scope="row"></td>
      <td>PDO mysqlnd</td>
      <td>Native Driver</td>
      <td></td>
    </tr><tr>
      <td scope="row">Python</td>
      <td>Connector/Python</td>
      <td>Native Driver</td>
      <td>See <a class="ulink" href="http://dev.mysql.com/doc/connector-python/en/" target="_top">MySQL Connector/Python Developer Guide</a>.</td>
    </tr><tr>
      <td scope="row">Python</td>
      <td>Connector/Python C Extension</td>
      <td><code class="literal">libmysqlclient</code></td>
      <td>See <a class="ulink" href="http://dev.mysql.com/doc/connector-python/en/" target="_top">MySQL Connector/Python Developer Guide</a>.</td>
    </tr><tr>
      <td scope="row"></td>
      <td>MySQLdb</td>
      <td><code class="literal">libmysqlclient</code></td>
      <td>See <a class="xref" href="connectors-apis.html#apis-python" title="27.11 MySQL Python API">Section 27.11, “MySQL Python API”</a>.</td>
    </tr><tr>
      <td scope="row">Ruby</td>
      <td>MySQL/Ruby</td>
      <td><code class="literal">libmysqlclient</code></td>
      <td>Uses <code class="literal">libmysqlclient</code>. See
        <a class="xref" href="connectors-apis.html#apis-ruby-mysqlruby" title="27.12.1 The MySQL/Ruby API">Section 27.12.1, “The MySQL/Ruby API”</a>.</td>
    </tr><tr>
      <td scope="row"></td>
      <td>Ruby/MySQL</td>
      <td>Native Driver</td>
      <td>See <a class="xref" href="connectors-apis.html#apis-ruby-rubymysql" title="27.12.2 The Ruby/MySQL API">Section 27.12.2, “The Ruby/MySQL API”</a>.</td>
    </tr><tr>
      <td scope="row">Scheme</td>
      <td><code class="literal">Myscsh</code></td>
      <td><code class="literal">libmysqlclient</code></td>
      <td>See
        <a class="ulink" href="https://github.com/aehrisch/myscsh" target="_top"><code class="literal">Myscsh</code></a>.</td>
    </tr><tr>
      <td scope="row">SPL</td>
      <td><code class="literal">sql_mysql</code></td>
      <td><code class="literal">libmysqlclient</code></td>
      <td>See
        <a class="ulink" href="http://www.clifford.at/spl/spldoc/sql_mysql.html" target="_top"><code class="literal">sql_mysql</code>
        for SPL</a>.</td>
    </tr><tr>
      <td scope="row">Tcl</td>
      <td>MySQLtcl</td>
      <td><code class="literal">libmysqlclient</code></td>
      <td>See <a class="xref" href="connectors-apis.html#apis-tcl" title="27.13 MySQL Tcl API">Section 27.13, “MySQL Tcl API”</a>.</td>
</tr></tbody></table>
</div>

</div>
<br class="table-break">
<div class="section">

<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="connector-c-info"></a>27.1 MySQL Connector/C</h2>

</div>

</div>

</div>
<a class="indexterm" name="idm140710576732208"></a><p>
    The MySQL Connector/C manual is published in standalone form, not as
    part of the MySQL Reference Manual. For information, see these
    documents:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
        Main manual: <a class="ulink" href="http://dev.mysql.com/doc/connector-c/en/" target="_top">MySQL Connector/C Developer Guide</a>
      </p></li><li class="listitem"><p>
        Release notes:
        <a class="ulink" href="http://dev.mysql.com/doc/relnotes/connector-c/en/" target="_top">MySQL
        Connector/C Release Notes</a>
</p></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="connector-cpp-info"></a>27.2 MySQL Connector/C++</h2>

</div>

</div>

</div>
<a class="indexterm" name="idm140710576725600"></a><a class="indexterm" name="idm140710576724560"></a><p>
    The MySQL Connector/C++ manual is published in standalone form, not
    as part of the MySQL Reference Manual. For information, see these
    documents:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
        Main manual: <a class="ulink" href="http://dev.mysql.com/doc/connector-cpp/en/" target="_top">MySQL Connector/C++ Developer Guide</a>
      </p></li><li class="listitem"><p>
        Release notes:
        <a class="ulink" href="http://dev.mysql.com/doc/relnotes/connector-cpp/en/" target="_top">MySQL
        Connector/C++ Release Notes</a>
</p></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="connector-j-info"></a>27.3 MySQL Connector/J</h2>

</div>

</div>

</div>
<a class="indexterm" name="idm140710576717920"></a><a class="indexterm" name="idm140710576716880"></a><p>
    The MySQL Connector/J manual is published in standalone form, not as
    part of the MySQL Reference Manual. For information, see these
    documents:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
        Main manual: <a class="ulink" href="http://dev.mysql.com/doc/connector-j/5.1/en/" target="_top">MySQL Connector/J 5.1 Developer Guide</a>
      </p></li><li class="listitem"><p>
        Release notes:
        <a class="ulink" href="http://dev.mysql.com/doc/relnotes/connector-j/en/" target="_top">MySQL
        Connector/J Release Notes</a>
</p></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="connector-net-info"></a>27.4 MySQL Connector/Net</h2>

</div>

</div>

</div>
<a class="indexterm" name="idm140710576710176"></a><p>
    The MySQL Connector/Net manual is published in standalone form, not
    as part of the MySQL Reference Manual. For information, see these
    documents:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
        Main manual: <a class="ulink" href="http://dev.mysql.com/doc/connector-net/en/" target="_top">MySQL Connector/Net Developer Guide</a>
      </p></li><li class="listitem"><p>
        Release notes:
        <a class="ulink" href="http://dev.mysql.com/doc/relnotes/connector-net/en/" target="_top">MySQL
        Connector/Net Release Notes</a>
</p></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="connector-odbc-info"></a>27.5 MySQL Connector/ODBC</h2>

</div>

</div>

</div>
<a class="indexterm" name="idm140710576703536"></a><p>
    The MySQL Connector/ODBC manual is published in standalone form, not
    as part of the MySQL Reference Manual. For information, see these
    documents:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
        Main manual: <a class="ulink" href="http://dev.mysql.com/doc/connector-odbc/en/" target="_top">MySQL Connector/ODBC Developer Guide</a>
      </p></li><li class="listitem"><p>
        Release notes:
        <a class="ulink" href="http://dev.mysql.com/doc/relnotes/connector-odbc/en/" target="_top">MySQL
        Connector/ODBC Release Notes</a>
</p></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="connector-python-info"></a>27.6 MySQL Connector/Python</h2>

</div>

</div>

</div>
<a class="indexterm" name="idm140710576696896"></a><a class="indexterm" name="idm140710576695856"></a><p>
    The MySQL Connector/Python manual is published in standalone form,
    not as part of the MySQL Reference Manual. For information, see
    these documents:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
        Main manual: <a class="ulink" href="http://dev.mysql.com/doc/connector-python/en/" target="_top">MySQL Connector/Python Developer Guide</a>
      </p></li><li class="listitem"><p>
        Release notes:
        <a class="ulink" href="http://dev.mysql.com/doc/relnotes/connector-python/en/" target="_top">MySQL
        Connector/Python Release Notes</a>
</p></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="libmysqld"></a>27.7 libmysqld, the Embedded MySQL Server Library</h2>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="connectors-apis.html#libmysqld-compiling">27.7.1 Compiling Programs with libmysqld</a></span></dt><dt><span class="section"><a href="connectors-apis.html#libmysqld-restrictions">27.7.2 Restrictions When Using the Embedded MySQL Server</a></span></dt><dt><span class="section"><a href="connectors-apis.html#libmysqld-options">27.7.3 Options with the Embedded Server</a></span></dt><dt><span class="section"><a href="connectors-apis.html#libmysqld-example">27.7.4 Embedded Server Examples</a></span></dt></dl>
</div>
<a class="indexterm" name="idm140710576689504"></a><a class="indexterm" name="idm140710576688464"></a><p>
    The embedded MySQL server library makes it possible to run a
    full-featured MySQL server inside a client application. The main
    benefits are increased speed and more simple management for embedded
    applications.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
      The <code class="literal">libmysqld</code> embedded server library is
      deprecated as of MySQL 5.7.19 and will be removed in MySQL 8.0.
</p>
</div>
<p>
    The embedded server library is based on the client/server version of
    MySQL, which is written in C/C++. Consequently, the embedded server
    also is written in C/C++. There is no embedded server available in
    other languages.
  </p><p>
    The API is identical for the embedded MySQL version and the
    client/server version. To change a threaded application to use the
    embedded library, you normally only have to add calls to the
    following functions.
</p>
<div class="table">
<a name="refman-apis-libmysqld-mysql-server-library-embeded-functions"></a><p class="title"><b>Table 27.2 MySQL Embedded Server Library Functions</b></p>
<div class="table-contents">
<table summary="MySQL embedded server library functions and descriptions of when the functions should be called."><col width="30%"><col width="70%"><thead><tr>
        <th scope="col"><p>
            Function
          </p></th>
        <th scope="col"><p>
            When to Call
          </p></th>
      </tr></thead><tbody><tr>
        <td scope="row"><p>
            <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a>
          </p></td>
        <td><p>
            Call it before any other MySQL function is called,
            preferably early in the <code class="literal">main()</code> function.
          </p></td>
      </tr><tr>
        <td scope="row"><p>
            <a class="link" href="connectors-apis.html#mysql-library-end" title="27.8.7.40 mysql_library_end()"><code class="literal">mysql_library_end()</code></a>
          </p></td>
        <td><p>
            Call it before your program exits.
          </p></td>
      </tr><tr>
        <td scope="row"><p>
            <a class="link" href="connectors-apis.html#mysql-thread-init" title="27.8.12.3 mysql_thread_init()"><code class="literal">mysql_thread_init()</code></a>
          </p></td>
        <td><p>
            Call it in each thread you create that accesses MySQL.
          </p></td>
      </tr><tr>
        <td scope="row"><a class="link" href="connectors-apis.html#mysql-thread-end" title="27.8.12.2 mysql_thread_end()"><code class="literal">mysql_thread_end()</code></a></td>
        <td>Call it before calling <code class="literal">pthread_exit()</code>.</td>
</tr></tbody></table>
</div>

</div>
<br class="table-break"><p>
    Then, link your code with <code class="filename">libmysqld.a</code> instead
    of <code class="filename">libmysqlclient.a</code>. To ensure binary
    compatibility between your application and the server library,
    always compile your application against headers for the same series
    of MySQL that was used to compile the server library. For example,
    if <code class="literal">libmysqld</code> was compiled against MySQL
    5.6 headers, do not compile your application against
    MySQL 5.7 headers, or vice versa.
  </p><p>
    Because the
    <code class="literal">mysql_library_<em class="replaceable"><code>xxx</code></em>()</code>
    functions are also included in
    <code class="filename">libmysqlclient.a</code>, you can change between the
    embedded and the client/server version by just linking your
    application with the right library. See
    <a class="xref" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()">Section 27.8.7.41, “mysql_library_init()”</a>.
  </p><p>
    One difference between the embedded server and the standalone server
    is that for the embedded server, authentication for connections is
    disabled by default.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="libmysqld-compiling"></a>27.7.1 Compiling Programs with libmysqld</h3>
</div>
</div>
</div>
<p>
      In precompiled binary MySQL distributions that include
      <code class="literal">libmysqld</code>, the embedded server library, MySQL
      builds the library using the appropriate vendor compiler if there
      is one.
    </p><p>
      To get a <code class="literal">libmysqld</code> library if you build MySQL
      from source yourself, you should configure MySQL with the
      <a class="link" href="installing.html#option_cmake_with_embedded_server"><code class="option">-DWITH_EMBEDDED_SERVER=1</code></a> option. See
      <a class="xref" href="installing.html#source-configuration-options" title="2.9.4 MySQL Source-Configuration Options">Section 2.9.4, “MySQL Source-Configuration Options”</a>.
    </p><p>
      When you link your program with <code class="literal">libmysqld</code>, you
      must also include the system-specific <code class="literal">pthread</code>
      libraries and some libraries that the MySQL server uses. You can
      get the full list of libraries by executing <a class="link" href="programs.html#mysql-config" title="4.7.1 mysql_config — Display Options for Compiling Clients"><span class="command"><strong>mysql_config
      --libmysqld-libs</strong></span></a>.
    </p><p>
      The correct flags for compiling and linking a threaded program
      must be used, even if you do not directly call any thread
      functions in your code.
    </p><p>
      To compile a C program to include the necessary files to embed the
      MySQL server library into an executable version of a program, the
      compiler will need to know where to find various files and need
      instructions on how to compile the program. The following example
      shows how a program could be compiled from the command line,
      assuming that you are using <span class="command"><strong>gcc</strong></span>, use the GNU C
      compiler:
    </p><pre data-lang="terminal" class="programlisting">
gcc mysql_test.c -o mysql_test \
`/usr/local/mysql/bin/mysql_config --include --libmysqld-libs`
</pre><p>
      Immediately following the <span class="command"><strong>gcc</strong></span> command is the
      name of the C program source file. After it, the
      <code class="option">-o</code> option is given to indicate that the file name
      that follows is the name that the compiler is to give to the
      output file, the compiled program. The next line of code tells the
      compiler to obtain the location of the include files and libraries
      and other settings for the system on which it is compiled. The
      <a class="link" href="programs.html#mysql-config" title="4.7.1 mysql_config — Display Options for Compiling Clients"><span class="command"><strong>mysql_config</strong></span></a> command is contained in backticks,
      not single quotation marks.
    </p><p>
      On some non-<span class="command"><strong>gcc</strong></span> platforms, the embedded library
      depends on C++ runtime libraries and linking against the embedded
      library might result in missing-symbol errors. To solve this, link
      using a C++ compiler or explicitly list the required libraries on
      the link command line.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="libmysqld-restrictions"></a>27.7.2 Restrictions When Using the Embedded MySQL Server</h3>

</div>

</div>

</div>
<p>
      The embedded server has the following limitations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          No user-defined functions (UDFs).
        </p></li><li class="listitem"><p>
          No stack trace on core dump.
        </p></li><li class="listitem"><p>
          You cannot set this up as a master or a slave (no
          replication).
        </p></li><li class="listitem"><p>
          Very large result sets may be unusable on low memory systems.
        </p></li><li class="listitem"><p>
          You cannot connect to an embedded server from an outside
          process with sockets or TCP/IP. However, you can connect to an
          intermediate application, which in turn can connect to an
          embedded server on the behalf of a remote client or outside
          process.
        </p></li><li class="listitem"><p>
          <code class="literal">InnoDB</code> is not reentrant in the embedded
          server and cannot be used for multiple connections, either
          successively or simultaneously.
        </p></li><li class="listitem"><p>
          The Event Scheduler is not available. Because of this, the
          <a class="link" href="server-administration.html#sysvar_event_scheduler"><code class="literal">event_scheduler</code></a> system
          variable is disabled.
        </p></li><li class="listitem"><p>
          The Performance Schema is not available.
        </p></li><li class="listitem"><p>
          The embedded server cannot share the same
          <a class="link" href="server-administration.html#sysvar_secure_file_priv"><code class="literal">secure_file_priv</code></a> directory
          with another server. As of MySQL 5.7.8, the default value for
          this directory can be set at build time with the
          <a class="link" href="installing.html#option_cmake_install_secure_file_priv_embeddeddir"><code class="option">INSTALL_SECURE_FILE_PRIV_EMBEDDEDDIR</code></a>
          <span class="command"><strong>CMake</strong></span> option.
</p></li></ul>
</div>
<p>
      Some of these limitations can be changed by editing the
      <code class="filename">mysql_embed.h</code> include file and recompiling
      MySQL.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="libmysqld-options"></a>27.7.3 Options with the Embedded Server</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140710576619312"></a><a class="indexterm" name="idm140710576617856"></a><a class="indexterm" name="idm140710576616368"></a><a class="indexterm" name="idm140710576614880"></a><p>
      Any options that may be given with the <a class="link" href="programs.html#mysqld" title="4.3.1 mysqld — The MySQL Server"><span class="command"><strong>mysqld</strong></span></a>
      server daemon, may be used with an embedded server library. Server
      options may be given in an array as an argument to the
      <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a>, which
      initializes the server. They also may be given in an option file
      like <code class="filename">my.cnf</code>. To specify an option file for a
      C program, use the <a class="link" href="programs.html#option_general_defaults-file"><code class="option">--defaults-file</code></a>
      option as one of the elements of the second argument of the
      <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a> function. See
      <a class="xref" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()">Section 27.8.7.41, “mysql_library_init()”</a>, for more information on the
      <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a> function.
    </p><p>
      Using option files can make it easier to switch between a
      client/server application and one where MySQL is embedded. Put
      common options under the <code class="literal">[server]</code> group. These
      are read by both MySQL versions. Client/server-specific options
      should go under the <code class="literal">[mysqld]</code> section. Put
      options specific to the embedded MySQL server library in the
      <code class="literal">[embedded]</code> section. Options specific to
      applications go under section labeled
      <code class="literal">[ApplicationName_SERVER]</code>. See
      <a class="xref" href="programs.html#option-files" title="4.2.6 Using Option Files">Section 4.2.6, “Using Option Files”</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="libmysqld-example"></a>27.7.4 Embedded Server Examples</h3>

</div>

</div>

</div>
<p>
      These two example programs should work without any changes on a
      Linux or FreeBSD system. For other operating systems, minor
      changes are needed, mostly with file paths. These examples are
      designed to give enough details for you to understand the problem,
      without the clutter that is a necessary part of a real
      application. The first example is very straightforward. The second
      example is a little more advanced with some error checking. The
      first is followed by a command-line entry for compiling the
      program. The second is followed by a GNUmake file that may be used
      for compiling instead.
    </p><p>
      <span class="bold"><strong>Example 1</strong></span>
    </p><p>
      <code class="filename">test1_libmysqld.c</code>
    </p><pre data-lang="c" class="programlisting">
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;stdarg.h&gt;
#include "mysql.h"

MYSQL *mysql;
MYSQL_RES *results;
MYSQL_ROW record;

static char *server_options[] = \
       { "mysql_test", "--defaults-file=my.cnf", NULL };
int num_elements = (sizeof(server_options) / sizeof(char *)) - 1;

static char *server_groups[] = { "libmysqld_server",
                                 "libmysqld_client", NULL };

int main(void)
{
   mysql_library_init(num_elements, server_options, server_groups);
   mysql = mysql_init(NULL);
   mysql_options(mysql, MYSQL_READ_DEFAULT_GROUP, "libmysqld_client");
   mysql_options(mysql, MYSQL_OPT_USE_EMBEDDED_CONNECTION, NULL);

   mysql_real_connect(mysql, NULL,NULL,NULL, "database1", 0,NULL,0);

   mysql_query(mysql, "SELECT column1, column2 FROM table1");

   results = mysql_store_result(mysql);

   while((record = mysql_fetch_row(results))) {
      printf("%s - %s \n", record[0], record[1]);
   }

   mysql_free_result(results);
   mysql_close(mysql);
   mysql_library_end();

   return 0;
}
</pre><p>
      Here is the command line for compiling the above program:
    </p><pre data-lang="terminal" class="programlisting">
gcc test1_libmysqld.c -o test1_libmysqld \
 `/usr/local/mysql/bin/mysql_config --include --libmysqld-libs`
</pre><p>
      <span class="bold"><strong>Example 2</strong></span>
    </p><p>
      To try the example, create an <code class="filename">test2_libmysqld</code>
      directory at the same level as the MySQL source directory. Save
      the <code class="filename">test2_libmysqld.c</code> source and the
      <code class="filename">GNUmakefile</code> in the directory, and run GNU
      <code class="filename">make</code> from inside the
      <code class="filename">test2_libmysqld</code> directory.
    </p><p>
      <code class="filename">test2_libmysqld.c</code>
    </p><pre data-lang="c" class="programlisting">
/*
 * A simple example client, using the embedded MySQL server library
*/

#include &lt;mysql.h&gt;
#include &lt;stdarg.h&gt;
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;

MYSQL *db_connect(const char *dbname);
void db_disconnect(MYSQL *db);
void db_do_query(MYSQL *db, const char *query);

const char *server_groups[] = {
  "test2_libmysqld_SERVER", "embedded", "server", NULL
};

int
main(int argc, char **argv)
{
  MYSQL *one, *two;

  /* mysql_library_init() must be called before any other mysql
   * functions.
   *
   * You can use mysql_library_init(0, NULL, NULL), and it
   * initializes the server using groups = {
   *   "server", "embedded", NULL
   *  }.
   *
   * In your $HOME/.my.cnf file, you probably want to put:

[test2_libmysqld_SERVER]
language = /path/to/source/of/mysql/sql/share/english

   * You could, of course, modify argc and argv before passing
   * them to this function.  Or you could create new ones in any
   * way you like.  But all of the arguments in argv (except for
   * argv[0], which is the program name) should be valid options
   * for the MySQL server.
   *
   * If you link this client against the normal mysqlclient
   * library, this function is just a stub that does nothing.
   */
  mysql_library_init(argc, argv, (char **)server_groups);

  one = db_connect("test");
  two = db_connect(NULL);

  db_do_query(one, "SHOW TABLE STATUS");
  db_do_query(two, "SHOW DATABASES");

  mysql_close(two);
  mysql_close(one);

  /* This must be called after all other mysql functions */
  mysql_library_end();

  exit(EXIT_SUCCESS);
}

static void
die(MYSQL *db, char *fmt, ...)
{
  va_list ap;
  va_start(ap, fmt);
  vfprintf(stderr, fmt, ap);
  va_end(ap);
  (void)putc('\n', stderr);
  if (db)
    db_disconnect(db);
  exit(EXIT_FAILURE);
}

MYSQL *
db_connect(const char *dbname)
{
  MYSQL *db = mysql_init(NULL);
  if (!db)
    die(db, "mysql_init failed: no memory");
  /*
   * Notice that the client and server use separate group names.
   * This is critical, because the server does not accept the
   * client's options, and vice versa.
   */
  mysql_options(db, MYSQL_READ_DEFAULT_GROUP, "test2_libmysqld_CLIENT");
  if (!mysql_real_connect(db, NULL, NULL, NULL, dbname, 0, NULL, 0))
    die(db, "mysql_real_connect failed: %s", mysql_error(db));

  return db;
}

void
db_disconnect(MYSQL *db)
{
  mysql_close(db);
}

void
db_do_query(MYSQL *db, const char *query)
{
  if (mysql_query(db, query) != 0)
    goto err;

  if (mysql_field_count(db) &gt; 0)
  {
    MYSQL_RES   *res;
    MYSQL_ROW    row, end_row;
    int num_fields;

    if (!(res = mysql_store_result(db)))
      goto err;
    num_fields = mysql_num_fields(res);
    while ((row = mysql_fetch_row(res)))
    {
      (void)fputs("&gt;&gt; ", stdout);
      for (end_row = row + num_fields; row &lt; end_row; ++row)
        (void)printf("%s\t", row ? (char*)*row : "NULL");
      (void)fputc('\n', stdout);
    }
    (void)fputc('\n', stdout);
    mysql_free_result(res);
  }
  else
    (void)printf("Affected rows: %lld\n", mysql_affected_rows(db));

  return;

err:
  die(db, "db_do_query failed: %s [%s]", mysql_error(db), query);
}
</pre><p>
      <code class="filename">GNUmakefile</code>
    </p><pre data-lang="terminal" class="programlisting">
# This assumes the MySQL software is installed in /usr/local/mysql
inc      := /usr/local/mysql/include/mysql
lib      := /usr/local/mysql/lib

# If you have not installed the MySQL software yet, try this instead
#inc      := $(HOME)/mysql-5.7/include
#lib      := $(HOME)/mysql-5.7/libmysqld

CC       := gcc
CPPFLAGS := -I$(inc) -D_THREAD_SAFE -D_REENTRANT
CFLAGS   := -g -W -Wall
LDFLAGS  := -static
# You can change -lmysqld to -lmysqlclient to use the
# client/server library
LDLIBS    = -L$(lib) -lmysqld -lm -ldl -lcrypt

ifneq (,$(shell grep FreeBSD /COPYRIGHT 2&gt;/dev/null))
# FreeBSD
LDFLAGS += -pthread
else
# Assume Linux
LDLIBS += -lpthread
endif

# This works for simple one-file test programs
sources := $(wildcard *.c)
objects := $(patsubst %c,%o,$(sources))
targets := $(basename $(sources))

all: $(targets)

clean:
        rm -f $(targets) $(objects) *.core
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="c-api"></a>27.8 MySQL C API</h2>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="connectors-apis.html#c-api-implementations">27.8.1 MySQL C API Implementations</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-multiple-installations">27.8.2 Simultaneous MySQL Server and Connector/C Installations</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-example-programs">27.8.3 Example C API Client Programs</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-building-running-clients">27.8.4 Building and Running C API Client Programs</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-data-structures">27.8.5 C API Data Structures</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-function-overview">27.8.6 C API Function Overview</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-functions">27.8.7 C API Function Descriptions</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-prepared-statements">27.8.8 C API Prepared Statements</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-prepared-statement-data-structures">27.8.9 C API Prepared Statement Data Structures</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-prepared-statement-function-overview">27.8.10 C API Prepared Statement Function Overview</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-prepared-statement-functions">27.8.11 C API Prepared Statement Function Descriptions</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-thread-functions">27.8.12 C API Threaded Function Descriptions</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-embedded-server-functions">27.8.13 C API Embedded Server Function Descriptions</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-plugin-functions">27.8.14 C API Client Plugin Functions</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-encrypted-connections">27.8.15 C API Encrypted Connection Support</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-multiple-queries">27.8.16 C API Multiple Statement Execution Support</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-prepared-statement-date-handling">27.8.17 C API Prepared Statement Handling of Date and Time Values</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-prepared-call-statements">27.8.18 C API Prepared CALL Statement Support</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-prepared-statement-problems">27.8.19 C API Prepared Statement Problems</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-auto-reconnect">27.8.20 C API Automatic Reconnection Control</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-common-issues">27.8.21 C API Common Issues</a></span></dt></dl>
</div>
<a class="indexterm" name="idm140710576573568"></a><a class="indexterm" name="idm140710576572080"></a><p>
    The C API provides low-level access to the MySQL client/server
    protocol and enables C programs to access database contents. The C
    API code is distributed with MySQL and implemented in the
    <code class="literal">libmysqlclient</code> library. See
    <a class="xref" href="connectors-apis.html#c-api-implementations" title="27.8.1 MySQL C API Implementations">Section 27.8.1, “MySQL C API Implementations”</a>.
  </p><p>
    Most other client APIs use the <code class="literal">libmysqlclient</code>
    library to communicate with the MySQL server. (Exceptions are
    Connector/J and Connector/Net.) This means that, for example, you
    can take advantage of many of the same environment variables that
    are used by other client programs because they are referenced from
    the library. For a list of these variables, see
    <a class="xref" href="programs.html#programs-overview" title="4.1 Overview of MySQL Programs">Section 4.1, “Overview of MySQL Programs”</a>.
  </p><p>
    For instructions on building client programs using the C API, see
    <a class="xref" href="connectors-apis.html#c-api-building-clients" title="27.8.4.1 Building C API Client Programs">Section 27.8.4.1, “Building C API Client Programs”</a>. For programming with
    threads, see <a class="xref" href="connectors-apis.html#c-api-threaded-clients" title="27.8.4.3 Writing C API Threaded Client Programs">Section 27.8.4.3, “Writing C API Threaded Client Programs”</a>. To create a
    standalone application which includes the "server" and "client" in
    the same program (and does not communicate with an external MySQL
    server), see <a class="xref" href="connectors-apis.html#libmysqld" title="27.7 libmysqld, the Embedded MySQL Server Library">Section 27.7, “libmysqld, the Embedded MySQL Server Library”</a>.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
      If, after an upgrade, you experience problems with compiled client
      programs, such as <code class="literal">Commands out of sync</code> or
      unexpected core dumps, the programs were probably compiled using
      old header or library files. In this case, check the date of the
      <code class="filename">mysql.h</code> file and
      <code class="filename">libmysqlclient.a</code> library used for compilation
      to verify that they are from the new MySQL distribution. If not,
      recompile the programs with the new headers and libraries.
      Recompilation might also be necessary for programs compiled
      against the shared client library if the library major version
      number has changed (for example, from
      <code class="filename">libmysqlclient.so.17</code> to
      <code class="filename">libmysqlclient.so.18</code>). For additional
      compatibility information, see
      <a class="xref" href="connectors-apis.html#c-api-running-clients" title="27.8.4.4 Running C API Client Programs">Section 27.8.4.4, “Running C API Client Programs”</a>.
</p>
</div>
<p>
    Clients have a maximum communication buffer size. The size of the
    buffer that is allocated initially (16KB) is automatically increased
    up to the maximum size (16MB by default). Because buffer sizes are
    increased only as demand warrants, simply increasing the maximum
    limit does not in itself cause more resources to be used. This size
    check is mostly a precaution against erroneous statements and
    communication packets.
  </p><p>
    The communication buffer must be large enough to contain a single
    SQL statement (for client-to-server traffic) and one row of returned
    data (for server-to-client traffic). Each session's communication
    buffer is dynamically enlarged to handle any query or row up to the
    maximum limit. For example, if you have
    <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">BLOB</code></a> values that contain up to 16MB
    of data, you must have a communication buffer limit of at least 16MB
    (in both server and client). The default maximum built into the
    client library is 1GB, but the default maximum in the server is 1MB.
    You can increase this by changing the value of the
    <a class="link" href="server-administration.html#sysvar_max_allowed_packet"><code class="literal">max_allowed_packet</code></a> parameter at
    server startup. See <a class="xref" href="server-administration.html#server-configuration" title="5.1.1 Configuring the Server">Section 5.1.1, “Configuring the Server”</a>.
  </p><p>
    The MySQL server shrinks each communication buffer to
    <a class="link" href="server-administration.html#sysvar_net_buffer_length"><code class="literal">net_buffer_length</code></a> bytes after each
    query. For clients, the size of the buffer associated with a
    connection is not decreased until the connection is closed, at which
    time client memory is reclaimed.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="c-api-implementations"></a>27.8.1 MySQL C API Implementations</h3>
</div>
</div>
</div>
<p>
      The MySQL C API is a C-based API that client applications written
      in C can use to communicate with MySQL Server. Client programs
      refer to C API header files at compile time and link to a C API
      library file at link time. The library comes in two versions,
      depending on how the application is intended to communicate with
      the server:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <code class="literal">libmysqlclient</code>: The client version of the
          library, used for applications that communicate over a network
          connection as a client of a standalone server process.
        </p></li><li class="listitem"><p>
          <code class="literal">libmysqld</code>: The embedded server version of
          the library, used for applications intended to include an
          embedded MySQL server within the application itself. The
          application communicates with its own private server instance.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
            The <code class="literal">libmysqld</code> embedded server library is
            deprecated as of MySQL 5.7.19 and will be removed in MySQL
            8.0.
</p>
</div>
</li></ul>
</div>
<p>
      Both libraries have the same interface. In terms of C API calls,
      an application communicates with a standalone server the same way
      it communicates with an embedded server. A given client can be
      built to communicate with a standalone or embedded server,
      depending on whether it is linked against
      <code class="literal">libmysqlclient</code> or <code class="literal">libmysqld</code>
      at build time.
    </p><p>
      There are two ways to obtain the C API header and library files
      required to build C API client programs:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          Install a MySQL Server distribution. Server distributions
          include both <code class="literal">libmysqlclient</code> and
          <code class="literal">libmysqld</code>.
        </p></li><li class="listitem"><p>
          Install a Connector/C distribution. Connector/C distributions include
          only <code class="literal">libmysqlclient</code>. They do not include
          <code class="literal">libmysqld</code>.
</p></li></ul>
</div>
<p>
      For both MySQL Server and Connector/C, you can install a binary
      distribution that contains the C API files pre-built, or you can
      use a source distribution and build the C API files yourself.
    </p><p>
      Normally, you install either a MySQL Server distribution or a Connector/C
      distribution, but not both. For information about issues involved
      with simultaneous MySQL Server and Connector/C installations, see
      <a class="xref" href="connectors-apis.html#c-api-multiple-installations" title="27.8.2 Simultaneous MySQL Server and Connector/C Installations">Section 27.8.2, “Simultaneous MySQL Server and Connector/C Installations”</a>.
    </p><p>
      The names of the library files to use when linking C API client
      applications depend on the library type and platform for which a
      distribution is built:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          On Unix (and Unix-like) sytems, the static library is
          <code class="filename">libmysqlclient.a</code>. The dynamic library is
          <code class="filename">libmysqlclient.so</code> on most Unix systems
          and <code class="filename">libmysqlclient.dylib</code> on OS X.
        </p><p>
          For distributions that include embedded server libraries, the
          corresponding library names begin with
          <code class="literal">libmysqld</code> rather than
          <code class="literal">libmysqlclient</code>.
        </p></li><li class="listitem"><p>
          On Windows, the static library is
          <code class="filename">mysqlclient.lib</code> and the dynamic library
          is <code class="filename">libmysql.dll</code>. Windows distributions
          also include <code class="filename">libmysql.lib</code>, a static
          import library needed for using the dynamic library.
        </p><p>
          For distributions that include embedded server libraries, the
          corresponding library names are
          <code class="filename">mysqlserver.lib</code>,
          <code class="filename">libmysqld.dll</code>, and
          <code class="filename">libmysqld.lib</code>.
        </p><p>
          Windows distributions also include a set of debug libraries.
          These have the same names as the nondebug libraries, but are
          located in the <code class="filename">lib/debug</code> library. You
          must use the debug libraries when compiling clients built
          using the debug C runtime.
</p></li></ul>
</div>
<p>
      On Unix, you may also see libraries that include
      <code class="literal">_r</code> in the names. Before MySQL 5.5, these were
      built as thread-safe (re-entrant) libraries separately from the
      non-<code class="literal">_r</code> libraries. As of 5.5, both libraries are
      the same and the <code class="literal">_r</code> names are symbolic links to
      the corresponding non-<code class="literal">_r</code> names. There is no
      need to use the <code class="literal">_r</code> libraries. For example, if
      you use <a class="link" href="programs.html#mysql-config" title="4.7.1 mysql_config — Display Options for Compiling Clients"><span class="command"><strong>mysql_config</strong></span></a> to obtain linker flags,
      you can use <a class="link" href="programs.html#mysql-config" title="4.7.1 mysql_config — Display Options for Compiling Clients"><span class="command"><strong>mysql_config --libs</strong></span></a> in all cases,
      even for threaded clients. There is no need to use
      <a class="link" href="programs.html#mysql-config" title="4.7.1 mysql_config — Display Options for Compiling Clients"><span class="command"><strong>mysql_config --libs_r</strong></span></a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="c-api-multiple-installations"></a>27.8.2 Simultaneous MySQL Server and Connector/C Installations</h3>

</div>

</div>

</div>
<p>
      MySQL Server and Connector/C installation packages both provide the files
      needed to build and run MySQL C API client programs. This section
      discusses when it is possible to install both products on the same
      system. For some packaging formats, this is possible without
      conflict. For others, both products cannot be installed at the
      same time.
    </p><p>
      This discussion assumes the use of similar package types for both
      products (for example, RPM packages for both products). It does
      not try to describe coexistence between packaging types (for
      example, use of RPM packages for one product and a
      <span class="command"><strong>tar</strong></span> file package for the other). Nor does it
      describe coexistence of packages provided by Oracle and those
      provided by third-party vendors.
    </p><p>
      If you install both products, it may be necessary to adjust your
      development tools or runtime environment to choose one set of
      header files and libraries over the other. See
      <a class="xref" href="connectors-apis.html#c-api-building-clients" title="27.8.4.1 Building C API Client Programs">Section 27.8.4.1, “Building C API Client Programs”</a>, and
      <a class="xref" href="connectors-apis.html#c-api-running-clients" title="27.8.4.4 Running C API Client Programs">Section 27.8.4.4, “Running C API Client Programs”</a>.
    </p><p>
      <span class="command"><strong>tar</strong></span> and Zip file packages install under the
      directory into which you unpack them. For example, you can unpack
      MySQL Server and Connector/C <span class="command"><strong>tar</strong></span> packages under
      <code class="filename">/usr/local</code> and they will unpack into distinct
      directory names without conflict.
    </p><p>
      Windows MSI installers use their own installation directory, so
      MySQL Server and Connector/C installers do not conflict.
    </p><p>
      OS X DMG packages install under the same parent directory but in a
      different subdirectory, so there is no conflict. For example:
    </p><pre data-lang="none" class="programlisting">
/usr/local/mysql-5.6.11-osx10.7-x86_64/
/usr/local/mysql-connector-c-6.1.0-osx10.7-x86/
</pre><p>
      Solaris PKG packages install under the same parent directory but
      in a different subdirectory, so there is no conflict. For example:
    </p><pre data-lang="none" class="programlisting">
/opt/mysql/mysql
/opt/mysql/connector-c
</pre><p>
      The Solaris Connector/C installer does not create any symlinks from
      system directories such as <code class="filename">/usr/bin</code> or
      <code class="filename">/usr/lib</code> into the installation directory.
      That must be done manually if desired after installation.
    </p><p>
      For RPM installations, there are several types of RPM packages.
      MySQL Server <code class="literal">shared</code> and
      <code class="literal">devel</code> RPM packages are similar to the
      corresponding Connector/C RPM packages. These RPM package types cannot
      coexist because the MySQL Server and Connector/C RPM packages use the
      same installation locations for the client library-related files.
      This means the following conditions hold:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          If MySQL Server <code class="literal">shared</code> and
          <code class="literal">devel</code> RPM packages are installed, they
          provide the C API headers and libraries, and there is no need
          to install the Connector/C RPM packages. To install the Connector/C packages
          anyway, you must first remove the corresponding MySQL Server
          packages.
        </p></li><li class="listitem"><p>
          To install MySQL Server RPM packages if you already have Connector/C
          RPM packages installed, you must first remove the Connector/C RPM
          packages.
</p></li></ul>
</div>
<p>
      MySQL Server RPM packages other than <code class="literal">shared</code> and
      <code class="literal">devel</code> do not conflict with Connector/C packages and
      can be installed if Connector/C is installed. This includes the main
      server RPM that includes the <a class="link" href="programs.html#mysqld" title="4.3.1 mysqld — The MySQL Server"><span class="command"><strong>mysqld</strong></span></a> server
      itself.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="c-api-example-programs"></a>27.8.3 Example C API Client Programs</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140710576487184"></a><a class="indexterm" name="idm140710576485728"></a><p>
      Many of the clients in MySQL source distributions are written in
      C, such as <a class="link" href="programs.html#mysql" title="4.5.1 mysql — The MySQL Command-Line Tool"><span class="command"><strong>mysql</strong></span></a>,
      <a class="link" href="programs.html#mysqladmin" title="4.5.2 mysqladmin — Client for Administering a MySQL Server"><span class="command"><strong>mysqladmin</strong></span></a>, and <a class="link" href="programs.html#mysqlshow" title="4.5.8 mysqlshow — Display Database, Table, and Column Information"><span class="command"><strong>mysqlshow</strong></span></a>.
      If you are looking for examples that demonstrate how to use the C
      API, take a look at these clients: Obtain a source distribution
      and look in its <code class="literal">client</code> directory. See
      <a class="xref" href="installing.html#getting-mysql" title="2.1.2 How to Get MySQL">Section 2.1.2, “How to Get MySQL”</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="c-api-building-running-clients"></a>27.8.4 Building and Running C API Client Programs</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="connectors-apis.html#c-api-building-clients">27.8.4.1 Building C API Client Programs</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-building-clients-pkg-config">27.8.4.2 Building C API Client Programs Using pkg-config</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-threaded-clients">27.8.4.3 Writing C API Threaded Client Programs</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-running-clients">27.8.4.4 Running C API Client Programs</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-server-client-versions">27.8.4.5 C API Server and Client Library Versions</a></span></dt></dl>
</div>
<p>
      The following sections provide information on building client
      programs that use the C API. Topics include compiling and linking
      clients, writing threaded clients, and troubleshooting runtime
      problems.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="c-api-building-clients"></a>27.8.4.1 Building C API Client Programs</h4>
</div>
</div>
</div>
<a class="indexterm" name="idm140710576475456"></a><a class="indexterm" name="idm140710576474000"></a><a class="indexterm" name="idm140710576472928"></a><a class="indexterm" name="idm140710576471440"></a><p>
        This section provides guidelines for compiling C programs that
        use the MySQL C API.
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="c-api-building-clients-compiling-mysql-clients-on-unix"></a>Compiling MySQL Clients on Unix</h5>
</div>
</div>
</div>
<a class="indexterm" name="idm140710576468144"></a><a class="indexterm" name="idm140710576466656"></a><p>
          The examples here use <span class="command"><strong>gcc</strong></span> as the compiler.
          A different compiler might be appropriate on some systems (for
          example, <span class="command"><strong>clang</strong></span> on OS X or FreeBSD, or Sun
          Studio on Solaris). Adjust the examples as necessary.
        </p><p>
          You may need to specify an <code class="option">-I</code> option when you
          compile client programs that use MySQL header files, so that
          the compiler can find them. For example, if the header files
          are installed in <code class="literal">/usr/local/mysql/include</code>,
          use this option in the compile command:
        </p><pre data-lang="none" class="programlisting">
-I/usr/local/mysql/include
</pre><p>
          MySQL clients must be linked using the
          <code class="option">-lmysqlclient</code> option in the link command. You
          may also need to specify a <code class="option">-L</code> option to tell
          the linker where to find the library. For example, if the
          library is installed in
          <code class="filename">/usr/local/mysql/lib</code>, use these options
          in the link command:
        </p><pre data-lang="none" class="programlisting">
-L/usr/local/mysql/lib -lmysqlclient
</pre><p>
          The path names may differ on your system. Adjust the
          <code class="option">-I</code> and <code class="option">-L</code> options as
          necessary.
        </p><p>
          To make it simpler to compile MySQL programs on Unix, use the
          <a class="link" href="programs.html#mysql-config" title="4.7.1 mysql_config — Display Options for Compiling Clients"><span class="command"><strong>mysql_config</strong></span></a> script. See
          <a class="xref" href="programs.html#mysql-config" title="4.7.1 mysql_config — Display Options for Compiling Clients">Section 4.7.1, “<span class="command"><strong>mysql_config</strong></span> — Display Options for Compiling Clients”</a>.
        </p><p>
          <a class="link" href="programs.html#mysql-config" title="4.7.1 mysql_config — Display Options for Compiling Clients"><span class="command"><strong>mysql_config</strong></span></a> displays the options needed
          for compiling or linking:
        </p><pre data-lang="bash" class="programlisting">
shell&gt; <strong class="userinput"><code>mysql_config --cflags</code></strong>
shell&gt; <strong class="userinput"><code>mysql_config --libs</code></strong>
</pre><p>
          You can run those commands to get the proper options and add
          them manually to compilation or link commands. Alternatively,
          include the output from <a class="link" href="programs.html#mysql-config" title="4.7.1 mysql_config — Display Options for Compiling Clients"><span class="command"><strong>mysql_config</strong></span></a>
          directly within command lines using backticks:
        </p><pre data-lang="bash" class="programlisting">
shell&gt; <strong class="userinput"><code>gcc -c `mysql_config --cflags` progname.c</code></strong>
shell&gt; <strong class="userinput"><code>gcc -o progname progname.o `mysql_config --libs`</code></strong>
</pre><p>
          On Unix, linking uses dynamic libraries by default. To link to
          the static client library instead, add its path name to the
          link command. For example, if the library is located in
          <code class="filename">/usr/local/mysql/lib</code>, link like this:
        </p><pre data-lang="bash" class="programlisting">
shell&gt; <strong class="userinput"><code>gcc -o progname progname.o /usr/local/mysql/lib/libmysqlclient.a</code></strong>
</pre><p>
          Or use <a class="link" href="programs.html#mysql-config" title="4.7.1 mysql_config — Display Options for Compiling Clients"><span class="command"><strong>mysql_config</strong></span></a> to provide the library
          name:
        </p><pre data-lang="bash" class="programlisting">
shell&gt; <strong class="userinput"><code>gcc -o progname progname.o `mysql_config --variable=pkglibdir`/libmysqlclient.a</code></strong>
</pre><p>
          <a class="link" href="programs.html#mysql-config" title="4.7.1 mysql_config — Display Options for Compiling Clients"><span class="command"><strong>mysql_config</strong></span></a> does not currently provide a
          way to list all libraries needed for static linking, so it
          might be necessary to name additional libraries on the link
          command (for example, <code class="literal">-lnsl -lsocket</code> on
          Solaris). To get an idea which libraries to add, use
          <a class="link" href="programs.html#mysql-config" title="4.7.1 mysql_config — Display Options for Compiling Clients"><span class="command"><strong>mysql_config --libs</strong></span></a> and <span class="command"><strong>ldd
          libmysqlclient.so</strong></span> (or <span class="command"><strong>otool -L
          libmysqlclient.dylib</strong></span> on OS X).
        </p><p>
          <span class="command"><strong>pkg-config</strong></span> can be used as an alternative to
          <a class="link" href="programs.html#mysql-config" title="4.7.1 mysql_config — Display Options for Compiling Clients"><span class="command"><strong>mysql_config</strong></span></a> for obtaining information such
          as compiler flags or link libraries required to compile MySQL
          applications. For example, the following pairs of commands are
          equivalent:
        </p><pre data-lang="bash" class="programlisting">
mysql_config --cflags
pkg-config --cflags mysqlclient

mysql_config --libs
pkg-config --libs mysqlclient
</pre><p>
          To produce flags for static linking, use this command:
        </p><pre data-lang="bash" class="programlisting">
pkg-config --static --libs mysqlclient
</pre><p>
          For more information, see
          <a class="xref" href="connectors-apis.html#c-api-building-clients-pkg-config" title="27.8.4.2 Building C API Client Programs Using pkg-config">Section 27.8.4.2, “Building C API Client Programs Using pkg-config”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="c-api-building-clients-compiling-mysql-clients-on-microsoft-windows"></a>Compiling MySQL Clients on Microsoft Windows</h5>

</div>

</div>

</div>
<a class="indexterm" name="idm140710576425728"></a><a class="indexterm" name="idm140710576424240"></a><p>
          To specify header and library file locations, use the
          facilities provided by your development environment.
        </p><p>
          To build C API clients on Windows, you must link in the C
          client library, as well as the Windows ws2_32 sockets library
          and Secur32 security library.
        </p><p>
          You link your code with either the dynamic or static C client
          library. On Windows, the static library is named
          <code class="filename">mysqlclient.lib</code> and the dynamic library
          is named <code class="filename">libmysql.dll</code>. In addition, the
          <code class="filename">libmysql.lib</code> static import library is
          needed for using the dynamic library. If the static C client
          library is used, the client application must be compiled with
          the same version of Visual Studio used to compile the C client
          library (which is Visual Studio 2013 for the static C client
          library built by Oracle).
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
            The <a class="ulink" href="http://dev.mysql.com/doc/connector-c/en/" target="_top">MySQL Connector/C</a> is
            a standalone, drop-in replacement of the MySQL C client
            libraries that come with the MySQL server distribution. The
            Oracle-built <a class="ulink" href="http://dev.mysql.com/doc/connector-c/en/" target="_top">MySQL
            Connector/C</a> contains currently two versions of the
            static client library, one built with Visual Studio 2013 and
            the other one with Visual Studio 2015; use the one that
            matches the Visual Studio version you use to compile your
            application.
</p>
</div>
<p>
          When using the Oracle-built MySQL C client library (or MySQL Connector/C),
          following these rules when it comes to linking the C runtime
          for your client application:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              For the Community version of the MySQL C client library
              (or the Community version of MySQL Connector/C):

</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                    <span class="emphasis"><em>For version 5.7.17 and before</em></span>
                    (or MySQL Connector/C Community 6.1.9 and before):

</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: square; "><li class="listitem"><p>
                          If linking to the static C client library,
                          link statically to the C runtime (use the
                          <code class="literal">/MT</code> compiler option).
                        </p></li><li class="listitem"><p>
                          If linking to the dynamic C client library,
                          link either statically or dynamically to the C
                          runtime (use either <code class="literal">/MT</code> or
                          <code class="literal">/MD</code> compiler option).
</p></li></ul>
</div>
<p>
                  </p></li><li class="listitem"><p>
                    <span class="emphasis"><em>For version 5.7.18 and later</em></span>
                    (or MySQL Connector/C Community 6.1.10 and later): Always link
                    dynamically to the C runtime (use the
                    <code class="literal">/MD</code> compiler option), whether you
                    are linking to the static or dynamic C client
                    library. Also, target hosts running the client
                    application need to have the
                    <a class="ulink" href="https://www.microsoft.com/en-us/download/details.aspx?id=40784" target="_top">Visual
                    C++ Redistributable for Visual Studio 2013</a>
                    installed if you are using the C client libraries,
                    or the
                    <a class="ulink" href="https://www.microsoft.com/en-us/download/details.aspx?id=48145" target="_top">Visual
                    C++ Redistributable for Visual Studio 2015</a>
                    installed if you are using MySQL Connector/C.
</p></li></ul>
</div>
<p>
            </p></li><li class="listitem"><p>
              For the Commercial version of the MySQL C client library
              (or the Commercial version of MySQL Connector/C):
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                  If linking to the static C client library, link
                  statically to the C runtime (use the<code class="literal">
                  /MT</code> compiler option).
                </p></li><li class="listitem"><p>
                  If linking to the dynamic C client library, link
                  either statically or dynamically to the C runtime (use
                  either <code class="literal">/MT</code> or
                  <code class="literal">/MD</code> compiler option).
</p></li></ul>
</div>
</li></ul>
</div>
<p>
          In general, when linking to a static MySQL C client library,
          the client library and the client application must use the
          same compiler option when it comes to linking the C
          runtime—that is, if your C client library is compiled
          with the <code class="literal">/MT</code> option, your client
          application should also be compiled with the
          <code class="literal">/MT</code> option, and so on (see
          <a class="ulink" href="http://msdn.microsoft.com/en-us/library/2kzt1wy3.aspx" target="_top">the
          MSDN page describing the C library linking options</a> for
          more details). Follow this rule when you are building your own
          static MySQL C client library (or MySQL Connector/C) from source and
          linking you client application to it.

</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
              <span class="emphasis"><em>Debug Mode:</em></span> Because of the
              above-mentioned rule, you cannot build your application in
              debug mode (with the <code class="literal">/MTd</code> or
              <code class="literal">/MDd</code> compiler option) and link it to
              the static C client library built by Oracle, which is
              <span class="emphasis"><em>not</em></span> built with the debug options;
              instead, you will have to build the static client library
              from source with the debug options.
</p>
</div>
<p>
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="c-api-building-clients-troubleshooting-problems-linking-to-the-mysql-client-library"></a>Troubleshooting Problems Linking to the MySQL Client Library</h5>

</div>

</div>

</div>
<a class="indexterm" name="idm140710576389904"></a><a class="indexterm" name="idm140710576388416"></a><a class="indexterm" name="idm140710576386928"></a><a class="indexterm" name="idm140710576385440"></a><a class="indexterm" name="idm140710576383952"></a><p>
          The MySQL client library includes SSL support built in. It is
          unnecessary to specify either <code class="literal">-lssl</code> or
          <code class="literal">-lcrypto</code> at link time. Doing so may in fact
          result in problems at runtime.
        </p><p>
          If the linker cannot find the MySQL client library, you might
          get undefined-reference errors for symbols that start with
          <code class="literal">mysql_</code>, such as those shown here:
        </p><pre data-lang="none" class="programlisting">
/tmp/ccFKsdPa.o: In function `main':
/tmp/ccFKsdPa.o(.text+0xb): undefined reference to `mysql_init'
/tmp/ccFKsdPa.o(.text+0x31): undefined reference to `mysql_real_connect'
/tmp/ccFKsdPa.o(.text+0x69): undefined reference to `mysql_error'
/tmp/ccFKsdPa.o(.text+0x9a): undefined reference to `mysql_close'
</pre><p>
          You should be able to solve this problem by adding
          <code class="literal">-L<em class="replaceable"><code>dir_path</code></em>
          -lmysqlclient</code> at the end of your link command, where
          <em class="replaceable"><code>dir_path</code></em> represents the path name
          of the directory where the client library is located. To
          determine the correct directory, try this command:
        </p><pre data-lang="bash" class="programlisting">
shell&gt; <strong class="userinput"><code>mysql_config --libs</code></strong>
</pre><p>
          The output from <a class="link" href="programs.html#mysql-config" title="4.7.1 mysql_config — Display Options for Compiling Clients"><span class="command"><strong>mysql_config</strong></span></a> might indicate
          other libraries that should be specified on the link command
          as well. You can include <a class="link" href="programs.html#mysql-config" title="4.7.1 mysql_config — Display Options for Compiling Clients"><span class="command"><strong>mysql_config</strong></span></a>
          output directly in your compile or link command using
          backticks. For example:
        </p><pre data-lang="bash" class="programlisting">
shell&gt; <strong class="userinput"><code>gcc -o progname progname.o `mysql_config --libs`</code></strong>
</pre><p>
          If an error occurs at link time that the
          <code class="literal">floor</code> symbol is undefined, link to the math
          library by adding <code class="option">-lm</code> to the end of the
          compile/link line. Similarly, if you get undefined-reference
          errors for other functions that should exist on your system,
          such as <code class="literal">connect()</code>, check the manual page
          for the function in question to determine which libraries you
          should add to the link command.
        </p><p>
          If you get undefined-reference errors such as the following
          for functions that do not exist on your system, it usually
          means that your MySQL client library was compiled on a system
          that is not 100% compatible with yours:
        </p><pre data-lang="bash" class="programlisting">
mf_format.o(.text+0x201): undefined reference to `__lxstat'
</pre><p>
          In this case, you should download the latest MySQL or Connector/C
          source distribution and compile the MySQL client library
          yourself. See <a class="xref" href="installing.html#source-installation" title="2.9 Installing MySQL from Source">Section 2.9, “Installing MySQL from Source”</a>, and
          <a class="ulink" href="http://dev.mysql.com/doc/connector-c/en/" target="_top">MySQL Connector/C Developer Guide</a>.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="c-api-building-clients-pkg-config"></a>27.8.4.2 Building C API Client Programs Using pkg-config</h4>

</div>

</div>

</div>
<p>
        MySQL distributions contain a
        <code class="filename">mysqlclient.pc</code> file that provides
        information about MySQL configuration for use by the
        <span class="command"><strong>pkg-config</strong></span> command. This enables
        <span class="command"><strong>pkg-config</strong></span> to be used as an alternative to
        <a class="link" href="programs.html#mysql-config" title="4.7.1 mysql_config — Display Options for Compiling Clients"><span class="command"><strong>mysql_config</strong></span></a> for obtaining information such
        as compiler flags or link libraries required to compile MySQL
        applications. For example, the following pairs of commands are
        equivalent:
      </p><pre data-lang="bash" class="programlisting">
mysql_config --cflags
pkg-config --cflags mysqlclient

mysql_config --libs
pkg-config --libs mysqlclient
</pre><p>
        The last <span class="command"><strong>pkg-config</strong></span> command produces flags
        for dynamic linking. To produce flags for static linking, use
        this command:
      </p><pre data-lang="bash" class="programlisting">
pkg-config --static --libs mysqlclient
</pre><p>
        On some platforms, the output with and without
        <code class="option">--static</code> might be the same.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
          <a class="indexterm" name="idm140710576352672"></a>

          <a class="indexterm" name="idm140710576351584"></a>

          If <span class="command"><strong>pkg-config</strong></span> does not find MySQL
          information, it might be necessary to set the
          <code class="literal">PKG_CONFIG_PATH</code> environment variable to the
          directory in which the <code class="filename">mysqlclient.pc</code>
          file is located, which by default is usually the
          <code class="filename">pkgconfig</code> directory under the MySQL
          library directory. For example (adjust the location
          appropriately):
        </p><pre data-lang="bash" class="programlisting">
export PKG_CONFIG_PATH=/usr/local/mysql/lib/pkgconfig # sh, bash, ...
setenv PKG_CONFIG_PATH /usr/local/mysql/lib/pkgconfig # csh, tcsh, ...
</pre><p>
          The <code class="filename">mysqlconfig.pc</code> installation location
          can be controlled using the
          <a class="link" href="installing.html#option_cmake_install_pkgconfigdir"><code class="option">INSTALL_PKGCONFIGDIR</code></a>
          <span class="command"><strong>CMake</strong></span> option. See
          <a class="xref" href="installing.html#source-configuration-options" title="2.9.4 MySQL Source-Configuration Options">Section 2.9.4, “MySQL Source-Configuration Options”</a>.
</p>
</div>
<p>
        The <code class="option">--variable</code> option takes a configuration
        variable name and displays the variable value:
      </p><pre data-lang="bash" class="programlisting">
pkg-config --variable=prefix mysqlclient     # installation prefix directory
pkg-config --variable=includedir mysqlclient # header file directory
pkg-config --variable=libdir mysqlclient     # library directory
</pre><p>
        To see which variable values <span class="command"><strong>pkg-config</strong></span> can
        display using the <code class="option">--variable</code> option, use this
        command:
      </p><pre data-lang="bash" class="programlisting">
pkg-config --print-variables mysqlclient
</pre><p>
        You can use <span class="command"><strong>pkg-config</strong></span> within a command line
        using backticks to include the output that it produces for
        particular options. For example, to compile and link a MySQL
        client program, use <span class="command"><strong>pkg-config</strong></span> as follows:
      </p><pre data-lang="bash" class="programlisting">
gcc -c `pkg-config --cflags mysqlclient` progname.c
gcc -o progname progname.o `pkg-config --libs mysqlclient`
</pre>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="c-api-threaded-clients"></a>27.8.4.3 Writing C API Threaded Client Programs</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710576332896"></a><a class="indexterm" name="idm140710576331440"></a><p>
        The client library is almost thread-safe. The biggest problem is
        that the subroutines in <code class="filename">sql/net_serv.cc</code>
        that read from sockets are not interrupt-safe. This was done
        with the thought that you might want to have your own alarm that
        can break a long read to a server. If you install interrupt
        handlers for the <code class="literal">SIGPIPE</code> interrupt, socket
        handling should be thread-safe.
      </p><p>
        To avoid aborting the program when a connection terminates,
        MySQL blocks <code class="literal">SIGPIPE</code> on the first call to
        <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a>,
        <a class="link" href="connectors-apis.html#mysql-init" title="27.8.7.37 mysql_init()"><code class="literal">mysql_init()</code></a>, or
        <a class="link" href="connectors-apis.html#mysql-connect" title="27.8.7.7 mysql_connect()"><code class="literal">mysql_connect()</code></a>. To use your own
        <code class="literal">SIGPIPE</code> handler, first call
        <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a>, then
        install your handler.
      </p><p>
        If <span class="quote">“<span class="quote">undefined symbol</span>”</span> errors occur when linking
        against the <code class="literal">libmysqlclient</code> client library, in
        most cases this is because you have not included the thread
        libraries on the link/compile command.
      </p><p>
        The client library is thread-safe per connection. You can let
        two threads share the same connection with the following
        caveats:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Multiple threads cannot send a query to the MySQL server at
            the same time on the same connection. In particular, you
            must ensure that between calls to
            <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a> and
            <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a> in one
            thread, no other thread uses the same connection. You must
            have a mutex lock around your pair of
            <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a> and
            <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a> calls.
            After <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a>
            returns, the lock can be released and other threads may
            query the same connection.
          </p><p>
            If you use POSIX threads, you can use
            <code class="literal">pthread_mutex_lock()</code> and
            <code class="literal">pthread_mutex_unlock()</code> to establish and
            release a mutex lock.
          </p></li><li class="listitem"><p>
            Many threads can access different result sets that are
            retrieved with
            <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a>.
          </p></li><li class="listitem"><p>
            To use <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a>,
            you must ensure that no other thread is using the same
            connection until the result set is closed. However, it
            really is best for threaded clients that share the same
            connection to use
            <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a>.
</p></li></ul>
</div>
<p>
        You need to know the following if you have a thread that did not
        create the connection to the MySQL database but is calling MySQL
        functions:
      </p><p>
        When you call <a class="link" href="connectors-apis.html#mysql-init" title="27.8.7.37 mysql_init()"><code class="literal">mysql_init()</code></a>,
        MySQL creates a thread-specific variable for the thread that is
        used by the debug library (among other things). If you call a
        MySQL function before the thread has called
        <a class="link" href="connectors-apis.html#mysql-init" title="27.8.7.37 mysql_init()"><code class="literal">mysql_init()</code></a>, the thread does
        not have the necessary thread-specific variables in place and
        you are likely to end up with a core dump sooner or later. To
        avoid problems, you must do the following:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
            Call <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a>
            before any other MySQL functions. It is not thread-safe, so
            call it before threads are created, or protect the call with
            a mutex.
          </p></li><li class="listitem"><p>
            Arrange for
            <a class="link" href="connectors-apis.html#mysql-thread-init" title="27.8.12.3 mysql_thread_init()"><code class="literal">mysql_thread_init()</code></a> to be
            called early in the thread handler before calling any MySQL
            function. If you call
            <a class="link" href="connectors-apis.html#mysql-init" title="27.8.7.37 mysql_init()"><code class="literal">mysql_init()</code></a>, it will call
            <a class="link" href="connectors-apis.html#mysql-thread-init" title="27.8.12.3 mysql_thread_init()"><code class="literal">mysql_thread_init()</code></a> for you.
          </p></li><li class="listitem"><p>
            In the thread, call
            <a class="link" href="connectors-apis.html#mysql-thread-end" title="27.8.12.2 mysql_thread_end()"><code class="literal">mysql_thread_end()</code></a> before
            calling <code class="literal">pthread_exit()</code>. This frees the
            memory used by MySQL thread-specific variables.
</p></li></ol>
</div>
<p>
        The preceding notes regarding
        <a class="link" href="connectors-apis.html#mysql-init" title="27.8.7.37 mysql_init()"><code class="literal">mysql_init()</code></a> also apply to
        <a class="link" href="connectors-apis.html#mysql-connect" title="27.8.7.7 mysql_connect()"><code class="literal">mysql_connect()</code></a>, which calls
        <a class="link" href="connectors-apis.html#mysql-init" title="27.8.7.37 mysql_init()"><code class="literal">mysql_init()</code></a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="c-api-running-clients"></a>27.8.4.4 Running C API Client Programs</h4>

</div>

</div>

</div>
<p>
        If, after an upgrade, you experience problems with compiled
        client programs, such as <code class="literal">Commands out of sync</code>
        or unexpected core dumps, the programs were probably compiled
        using old header or library files. In this case, check the date
        of the <code class="filename">mysql.h</code> file and
        <code class="filename">libmysqlclient.a</code> library used for
        compilation to verify that they are from the new MySQL
        distribution. If not, recompile the programs with the new
        headers and libraries. Recompilation might also be necessary for
        programs compiled against the shared client library if the
        library major version number has changed (for example, from
        <code class="filename">libmysqlclient.so.17</code> to
        <code class="filename">libmysqlclient.so.18</code>).
      </p><p>
        The major client library version determines compatibility. (For
        example, for <code class="literal">libmysqlclient.so.18.1.0</code>, the
        major version is 18.) For this reason, the libraries shipped
        with newer versions of MySQL are drop-in replacements for older
        versions that have the same major number. As long as the major
        library version is the same, you can upgrade the library and old
        applications should continue to work with it.
      </p><p>
        Undefined-reference errors might occur at runtime when you try
        to execute a MySQL program. If these errors specify symbols that
        start with <code class="literal">mysql_</code> or indicate that the
        <code class="literal">libmysqlclient</code> library cannot be found, it
        means that your system cannot find the shared
        <code class="filename">libmysqlclient.so</code> library. The solution to
        this problem is to tell your system to search for shared
        libraries in the directory where that library is located. Use
        whichever of the following methods is appropriate for your
        system:
</p><a class="indexterm" name="idm140710576274192"></a><a class="indexterm" name="idm140710576273104"></a><a class="indexterm" name="idm140710576271616"></a><a class="indexterm" name="idm140710576270528"></a>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Add the path of the directory where
            <code class="filename">libmysqlclient.so</code> is located to the
            <code class="literal">LD_LIBRARY_PATH</code> or
            <code class="literal">LD_LIBRARY</code> environment variable.
          </p></li><li class="listitem"><p>
            On OS X, add the path of the directory where
            <code class="filename">libmysqlclient.dylib</code> is located to the
            <code class="literal">DYLD_LIBRARY_PATH</code> environment variable.
          </p></li><li class="listitem"><p>
            Copy the shared-library files (such as
            <code class="filename">libmysqlclient.so</code>) to some directory
            that is searched by your system, such as
            <code class="filename">/lib</code>, and update the shared library
            information by executing <code class="literal">ldconfig</code>. Be
            sure to copy all related files. A shared library might exist
            under several names, using symlinks to provide the alternate
            names.
</p></li></ul>
</div>
<p>
        If the application is linked to the embedded server library,
        runtime error messages will indicate the
        <code class="literal">libmysqld</code> rather than
        <code class="literal">libmysqlclient</code> library, but the solution to
        the problem is the same as just described.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="c-api-server-client-versions"></a>27.8.4.5 C API Server and Client Library Versions</h4>

</div>

</div>

</div>
<p>
        The string and numeric forms of the MySQL server version are
        available at compile time as the values of the
        <code class="literal">MYSQL_SERVER_VERSION</code> and
        <code class="literal">MYSQL_VERSION_ID</code> macros, and at runtime as
        the values of the
        <a class="link" href="connectors-apis.html#mysql-get-server-info" title="27.8.7.32 mysql_get_server_info()"><code class="literal">mysql_get_server_info()</code></a> and
        <a class="link" href="connectors-apis.html#mysql-get-server-version" title="27.8.7.33 mysql_get_server_version()"><code class="literal">mysql_get_server_version()</code></a>
        functions.
      </p><p>
        The MySQL client library version depends on the type of
        distribution that provides the library:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            For MySQL distributions, the client library version is the
            MySQL version. The string and numeric forms of this version
            are available at compile time as the values of the
            <code class="literal">MYSQL_SERVER_VERSION</code> and
            <code class="literal">MYSQL_VERSION_ID</code> macros, and at runtime
            as the values of the
            <a class="link" href="connectors-apis.html#mysql-get-client-info" title="27.8.7.27 mysql_get_client_info()"><code class="literal">mysql_get_client_info()</code></a> and
            <a class="link" href="connectors-apis.html#mysql-get-client-version" title="27.8.7.28 mysql_get_client_version()"><code class="literal">mysql_get_client_version()</code></a>
            functions.
          </p><p>
            The <code class="literal">LIBMYSQL_VERSION</code> and
            <code class="literal">LIBMYSQL_VERSION_ID</code> macros have the same
            values as <code class="literal">MYSQL_SERVER_VERSION</code> and
            <code class="literal">MYSQL_VERSION_ID</code> and the two sets of
            macros can be used interchangeably.
          </p></li><li class="listitem"><p>
            For Connector/C distributions, the client library version is
            the Connector/C version. The string and numeric forms of
            this version are available at compile time as the values of
            the <code class="literal">LIBMYSQL_VERSION</code> and
            <code class="literal">LIBMYSQL_VERSION_ID</code> macros, and at
            runtime as the values of the
            <a class="link" href="connectors-apis.html#mysql-get-client-info" title="27.8.7.27 mysql_get_client_info()"><code class="literal">mysql_get_client_info()</code></a> and
            <a class="link" href="connectors-apis.html#mysql-get-client-version" title="27.8.7.28 mysql_get_client_version()"><code class="literal">mysql_get_client_version()</code></a>
            functions.
          </p><p>
            The <code class="literal">MYSQL_SERVER_VERSION</code> and
            <code class="literal">MYSQL_VERSION_ID</code> macros indicate the
            string and numeric forms of the MySQL version on which the
            Connector/C distribution is based.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="c-api-data-structures"></a>27.8.5 C API Data Structures</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140710576233904"></a><a class="indexterm" name="idm140710576232416"></a><p>
      This section describes C API data structures other than those used
      for prepared statements. For information about the latter, see
      <a class="xref" href="connectors-apis.html#c-api-prepared-statement-data-structures" title="27.8.9 C API Prepared Statement Data Structures">Section 27.8.9, “C API Prepared Statement Data Structures”</a>.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <a class="indexterm" name="idm140710576228640"></a>

          <code class="literal">MYSQL</code>
        </p><p>
          This structure represents handler for one database connection.
          It is used for almost all MySQL functions. Do not try to make
          a copy of a <code class="literal">MYSQL</code> structure. There is no
          guarantee that such a copy will be usable.
        </p></li><li class="listitem"><p>
          <a class="indexterm" name="idm140710576224752"></a>

          <code class="literal">MYSQL_RES</code>
        </p><p>
          This structure represents the result of a query that returns
          rows (<a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a>,
          <a class="link" href="sql-syntax.html#show" title="13.7.5 SHOW Syntax"><code class="literal">SHOW</code></a>,
          <a class="link" href="sql-syntax.html#describe" title="13.8.1 DESCRIBE Syntax"><code class="literal">DESCRIBE</code></a>,
          <a class="link" href="sql-syntax.html#explain" title="13.8.2 EXPLAIN Syntax"><code class="literal">EXPLAIN</code></a>). The information
          returned from a query is called the <span class="emphasis"><em>result
          set</em></span> in the remainder of this section.
        </p></li><li class="listitem"><p>
          <a class="indexterm" name="idm140710576216320"></a>

          <code class="literal">MYSQL_ROW</code>
        </p><p>
          This is a type-safe representation of one row of data. It is
          currently implemented as an array of counted byte strings.
          (You cannot treat these as null-terminated strings if field
          values may contain binary data, because such values may
          contain null bytes internally.) Rows are obtained by calling
          <a class="link" href="connectors-apis.html#mysql-fetch-row" title="27.8.7.21 mysql_fetch_row()"><code class="literal">mysql_fetch_row()</code></a>.
        </p></li><li class="listitem"><p>
          <a class="indexterm" name="idm140710576211808"></a>

          <code class="literal">MYSQL_FIELD</code>
        </p><p>
          This structure contains metadata: information about a field,
          such as the field's name, type, and size. Its members are
          described in more detail later in this section. You may obtain
          the <code class="literal">MYSQL_FIELD</code> structures for each field
          by calling <a class="link" href="connectors-apis.html#mysql-fetch-field" title="27.8.7.17 mysql_fetch_field()"><code class="literal">mysql_fetch_field()</code></a>
          repeatedly. Field values are not part of this structure; they
          are contained in a <code class="literal">MYSQL_ROW</code> structure.
        </p></li><li class="listitem"><p>
          <a class="indexterm" name="idm140710576205760"></a>

          <code class="literal">MYSQL_FIELD_OFFSET</code>
        </p><p>
          This is a type-safe representation of an offset into a MySQL
          field list. (Used by
          <a class="link" href="connectors-apis.html#mysql-field-seek" title="27.8.7.23 mysql_field_seek()"><code class="literal">mysql_field_seek()</code></a>.) Offsets
          are field numbers within a row, beginning at zero.
        </p></li><li class="listitem"><p>
          <a class="indexterm" name="idm140710576201232"></a>

          <a class="indexterm" name="idm140710576200160"></a>

          <code class="literal">my_ulonglong</code>
        </p><p>
          The type used for the number of rows and for
          <a class="link" href="connectors-apis.html#mysql-affected-rows" title="27.8.7.1 mysql_affected_rows()"><code class="literal">mysql_affected_rows()</code></a>,
          <a class="link" href="connectors-apis.html#mysql-num-rows" title="27.8.7.49 mysql_num_rows()"><code class="literal">mysql_num_rows()</code></a>, and
          <a class="link" href="connectors-apis.html#mysql-insert-id" title="27.8.7.38 mysql_insert_id()"><code class="literal">mysql_insert_id()</code></a>. This type
          provides a range of <code class="literal">0</code> to
          <code class="literal">1.84e19</code>.
        </p><p>
          Some functions that return a row count using this type return
          -1 as an unsigned value to indicate an error or exceptional
          condition. You can check for -1 by comparing the return value
          to <code class="literal">(my_ulonglong)-1</code> (or to
          <code class="literal">(my_ulonglong)~0</code>, which is equivalent).
        </p><p>
          On some systems, attempting to print a value of type
          <code class="literal">my_ulonglong</code> does not work. To print such a
          value, convert it to <code class="literal">unsigned long</code> and use
          a <code class="literal">%lu</code> print format. Example:
        </p><pre data-lang="c" class="programlisting">
printf ("Number of rows: %lu\n",
        (unsigned long) mysql_num_rows(result));
</pre></li><li class="listitem"><p>
          <a class="indexterm" name="idm140710576185696"></a>

          <a class="indexterm" name="idm140710576184624"></a>

          <code class="literal">my_bool</code>
        </p><p>
          A boolean type, for values that are true (nonzero) or false
          (zero).
</p></li></ul>
</div>
<p>
      The <code class="literal">MYSQL_FIELD</code> structure contains the members
      described in the following list. The definitions apply primarily
      for columns of result sets such as those produced by
      <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a> statements.
      <code class="literal">MYSQL_FIELD</code> structures are also used to provide
      metadata for <code class="literal">OUT</code> and <code class="literal">INOUT</code>
      parameters returned from stored procedures executed using prepared
      <a class="link" href="sql-syntax.html#call" title="13.2.1 CALL Syntax"><code class="literal">CALL</code></a> statements. For such
      parameters, some of the structure members have a meaning different
      from the meaning for column values.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <code class="literal">char * name</code>
        </p><p>
          The name of the field, as a null-terminated string. If the
          field was given an alias with an <code class="literal">AS</code> clause,
          the value of <code class="literal">name</code> is the alias. For a
          procedure parameter, the parameter name.
        </p></li><li class="listitem"><p>
          <code class="literal">char * org_name</code>
        </p><p>
          The name of the field, as a null-terminated string. Aliases
          are ignored. For expressions, the value is an empty string.
          For a procedure parameter, the parameter name.
        </p></li><li class="listitem"><p>
          <code class="literal">char * table</code>
        </p><p>
          The name of the table containing this field, if it is not a
          calculated field. For calculated fields, the
          <code class="literal">table</code> value is an empty string. If the
          column is selected from a view, <code class="literal">table</code> names
          the view. If the table or view was given an alias with an
          <code class="literal">AS</code> clause, the value of
          <code class="literal">table</code> is the alias. For a
          <a class="link" href="sql-syntax.html#union" title="13.2.9.3 UNION Syntax"><code class="literal">UNION</code></a>, the value is the empty
          string. For a procedure parameter, the procedure name.
        </p></li><li class="listitem"><p>
          <code class="literal">char * org_table</code>
        </p><p>
          The name of the table, as a null-terminated string. Aliases
          are ignored. If the column is selected from a view,
          <code class="literal">org_table</code> names the view. If the column is
          selected from a derived table, <code class="literal">org_table</code>
          names the base table. If a derived table wraps a view,
          <code class="literal">org_table</code> still names the base table. If
          the column is an expression, <code class="literal">org_table</code> is
          the empty string. For a <a class="link" href="sql-syntax.html#union" title="13.2.9.3 UNION Syntax"><code class="literal">UNION</code></a>,
          the value is the empty string. For a procedure parameter, the
          value is the procedure name.
        </p></li><li class="listitem"><p>
          <code class="literal">char * db</code>
        </p><p>
          The name of the database that the field comes from, as a
          null-terminated string. If the field is a calculated field,
          <code class="literal">db</code> is an empty string. For a
          <a class="link" href="sql-syntax.html#union" title="13.2.9.3 UNION Syntax"><code class="literal">UNION</code></a>, the value is the empty
          string. For a procedure parameter, the name of the database
          containing the procedure.
        </p></li><li class="listitem"><p>
          <code class="literal">char * catalog</code>
        </p><p>
          The catalog name. This value is always
          <code class="literal">"def"</code>.
        </p></li><li class="listitem"><p>
          <code class="literal">char * def</code>
        </p><p>
          The default value of this field, as a null-terminated string.
          This is set only if you use
          <a class="link" href="connectors-apis.html#mysql-list-fields" title="27.8.7.43 mysql_list_fields()"><code class="literal">mysql_list_fields()</code></a>.
        </p></li><li class="listitem"><p>
          <code class="literal">unsigned long length</code>
        </p><p>
          The width of the field. This corresponds to the display
          length, in bytes.
        </p><p>
          The server determines the <code class="literal">length</code> value
          before it generates the result set, so this is the minimum
          length required for a data type capable of holding the largest
          possible value from the result column, without knowing in
          advance the actual values that will be produced by the query
          for the result set.
        </p></li><li class="listitem"><p>
          <code class="literal">unsigned long max_length</code>
        </p><p>
          The maximum width of the field for the result set (the length
          in bytes of the longest field value for the rows actually in
          the result set). If you use
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a> or
          <a class="link" href="connectors-apis.html#mysql-list-fields" title="27.8.7.43 mysql_list_fields()"><code class="literal">mysql_list_fields()</code></a>, this
          contains the maximum length for the field. If you use
          <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a>, the value
          of this variable is zero.
        </p><p>
          The value of <code class="literal">max_length</code> is the length of
          the string representation of the values in the result set. For
          example, if you retrieve a
          <a class="link" href="data-types.html#floating-point-types" title="11.2.3 Floating-Point Types (Approximate Value) - FLOAT, DOUBLE"><code class="literal">FLOAT</code></a> column and the
          <span class="quote">“<span class="quote">widest</span>”</span> value is <code class="literal">-12.345</code>,
          <code class="literal">max_length</code> is 7 (the length of
          <code class="literal">'-12.345'</code>).
        </p><p>
          If you are using prepared statements,
          <code class="literal">max_length</code> is not set by default because
          for the binary protocol the lengths of the values depend on
          the types of the values in the result set. (See
          <a class="xref" href="connectors-apis.html#c-api-prepared-statement-data-structures" title="27.8.9 C API Prepared Statement Data Structures">Section 27.8.9, “C API Prepared Statement Data Structures”</a>.)
          If you want the <code class="literal">max_length</code> values anyway,
          enable the <code class="literal">STMT_ATTR_UPDATE_MAX_LENGTH</code>
          option with
          <a class="link" href="connectors-apis.html#mysql-stmt-attr-set" title="27.8.11.3 mysql_stmt_attr_set()"><code class="literal">mysql_stmt_attr_set()</code></a> and the
          lengths will be set when you call
          <a class="link" href="connectors-apis.html#mysql-stmt-store-result" title="27.8.11.28 mysql_stmt_store_result()"><code class="literal">mysql_stmt_store_result()</code></a>.
          (See <a class="xref" href="connectors-apis.html#mysql-stmt-attr-set" title="27.8.11.3 mysql_stmt_attr_set()">Section 27.8.11.3, “mysql_stmt_attr_set()”</a>, and
          <a class="xref" href="connectors-apis.html#mysql-stmt-store-result" title="27.8.11.28 mysql_stmt_store_result()">Section 27.8.11.28, “mysql_stmt_store_result()”</a>.)
        </p></li><li class="listitem"><p>
          <code class="literal">unsigned int name_length</code>
        </p><p>
          The length of <code class="literal">name</code>.
        </p></li><li class="listitem"><p>
          <code class="literal">unsigned int org_name_length</code>
        </p><p>
          The length of <code class="literal">org_name</code>.
        </p></li><li class="listitem"><p>
          <code class="literal">unsigned int table_length</code>
        </p><p>
          The length of <code class="literal">table</code>.
        </p></li><li class="listitem"><p>
          <code class="literal">unsigned int org_table_length</code>
        </p><p>
          The length of <code class="literal">org_table</code>.
        </p></li><li class="listitem"><p>
          <code class="literal">unsigned int db_length</code>
        </p><p>
          The length of <code class="literal">db</code>.
        </p></li><li class="listitem"><p>
          <code class="literal">unsigned int catalog_length</code>
        </p><p>
          The length of <code class="literal">catalog</code>.
        </p></li><li class="listitem"><p>
          <code class="literal">unsigned int def_length</code>
        </p><p>
          The length of <code class="literal">def</code>.
        </p></li><li class="listitem"><p>
          <code class="literal">unsigned int flags</code>
        </p><p>
          Bit-flags that describe the field. The
          <code class="literal">flags</code> value may have zero or more of the
          bits set that are shown in the following table.
</p>
<div class="informaltable">
<table summary="Bit-flag values and a description of each flag."><col width="40%"><col width="60%"><thead><tr>
              <th scope="col">Flag Value</th>
              <th scope="col">Flag Description</th>
            </tr></thead><tbody><tr>
              <td scope="row"><code class="literal">NOT_NULL_FLAG</code></td>
              <td>Field cannot be <code class="literal">NULL</code></td>
            </tr><tr>
              <td scope="row"><code class="literal">PRI_KEY_FLAG</code></td>
              <td>Field is part of a primary key</td>
            </tr><tr>
              <td scope="row"><code class="literal">UNIQUE_KEY_FLAG</code></td>
              <td>Field is part of a unique key</td>
            </tr><tr>
              <td scope="row"><code class="literal">MULTIPLE_KEY_FLAG</code></td>
              <td>Field is part of a nonunique key</td>
            </tr><tr>
              <td scope="row"><code class="literal">UNSIGNED_FLAG</code></td>
              <td>Field has the <code class="literal">UNSIGNED</code> attribute</td>
            </tr><tr>
              <td scope="row"><code class="literal">ZEROFILL_FLAG</code></td>
              <td>Field has the <code class="literal">ZEROFILL</code> attribute</td>
            </tr><tr>
              <td scope="row"><code class="literal">BINARY_FLAG</code></td>
              <td>Field has the <code class="literal">BINARY</code> attribute</td>
            </tr><tr>
              <td scope="row"><code class="literal">AUTO_INCREMENT_FLAG</code></td>
              <td>Field has the <code class="literal">AUTO_INCREMENT</code> attribute</td>
            </tr><tr>
              <td scope="row"><code class="literal">ENUM_FLAG</code></td>
              <td>Field is an <a class="link" href="data-types.html#enum" title="11.4.4 The ENUM Type"><code class="literal">ENUM</code></a></td>
            </tr><tr>
              <td scope="row"><code class="literal">SET_FLAG</code></td>
              <td>Field is a <a class="link" href="data-types.html#set" title="11.4.5 The SET Type"><code class="literal">SET</code></a></td>
            </tr><tr>
              <td scope="row"><code class="literal">BLOB_FLAG</code></td>
              <td>Field is a <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">BLOB</code></a> or
                <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">TEXT</code></a> (deprecated)</td>
            </tr><tr>
              <td scope="row"><code class="literal">TIMESTAMP_FLAG</code></td>
              <td>Field is a <a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">TIMESTAMP</code></a> (deprecated)</td>
            </tr><tr>
              <td scope="row"><code class="literal">NUM_FLAG</code></td>
              <td>Field is numeric; see additional notes following table</td>
            </tr><tr>
              <td scope="row"><code class="literal">NO_DEFAULT_VALUE_FLAG</code></td>
              <td>Field has no default value; see additional notes following table</td>
</tr></tbody></table>
</div>
<p>
          Some of these flags indicate data type information and are
          superseded by or used in conjunction with the
          <code class="literal">MYSQL_TYPE_<em class="replaceable"><code>xxx</code></em></code>
          value in the <code class="literal">field-&gt;type</code> member
          described later:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
              To check for <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">BLOB</code></a> or
              <a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">TIMESTAMP</code></a> values, check
              whether <code class="literal">type</code> is
              <code class="literal">MYSQL_TYPE_BLOB</code> or
              <code class="literal">MYSQL_TYPE_TIMESTAMP</code>. (The
              <code class="literal">BLOB_FLAG</code> and
              <code class="literal">TIMESTAMP_FLAG</code> flags are unneeded.)
            </p></li><li class="listitem"><p>
              <a class="link" href="data-types.html#enum" title="11.4.4 The ENUM Type"><code class="literal">ENUM</code></a> and
              <a class="link" href="data-types.html#set" title="11.4.5 The SET Type"><code class="literal">SET</code></a> values are returned as
              strings. For these, check that the <code class="literal">type</code>
              value is <code class="literal">MYSQL_TYPE_STRING</code> and that the
              <code class="literal">ENUM_FLAG</code> or
              <code class="literal">SET_FLAG</code> flag is set in the
              <code class="literal">flags</code> value.
</p></li></ul>
</div>
<p>
          <code class="literal">NUM_FLAG</code> indicates that a column is
          numeric. This includes columns with a type of
          <code class="literal">MYSQL_TYPE_DECIMAL</code>,
          <code class="literal">MYSQL_TYPE_NEWDECIMAL</code>,
          <code class="literal">MYSQL_TYPE_TINY</code>,
          <code class="literal">MYSQL_TYPE_SHORT</code>,
          <code class="literal">MYSQL_TYPE_LONG</code>,
          <code class="literal">MYSQL_TYPE_FLOAT</code>,
          <code class="literal">MYSQL_TYPE_DOUBLE</code>,
          <code class="literal">MYSQL_TYPE_NULL</code>,
          <code class="literal">MYSQL_TYPE_LONGLONG</code>,
          <code class="literal">MYSQL_TYPE_INT24</code>, and
          <code class="literal">MYSQL_TYPE_YEAR</code>.
        </p><p>
          <code class="literal">NO_DEFAULT_VALUE_FLAG</code> indicates that a
          column has no <code class="literal">DEFAULT</code> clause in its
          definition. This does not apply to <code class="literal">NULL</code>
          columns (because such columns have a default of
          <code class="literal">NULL</code>), or to
          <code class="literal">AUTO_INCREMENT</code> columns (which have an
          implied default value).
        </p><p>
          The following example illustrates a typical use of the
          <code class="literal">flags</code> value:
        </p><pre data-lang="c" class="programlisting">
if (field-&gt;flags &amp; NOT_NULL_FLAG)
    printf("Field cannot be null\n");
</pre><p>
          You may use the convenience macros shown in the following
          table to determine the boolean status of the
          <code class="literal">flags</code> value.
</p>
<div class="informaltable">
<table summary="Flag status values and a description of each flag."><col width="40%"><col width="60%"><thead><tr>
              <th scope="col">Flag Status</th>
              <th scope="col">Description</th>
            </tr></thead><tbody><tr>
              <td scope="row"><code class="literal">IS_NOT_NULL(flags)</code></td>
              <td>True if this field is defined as <code class="literal">NOT NULL</code></td>
            </tr><tr>
              <td scope="row"><code class="literal">IS_PRI_KEY(flags)</code></td>
              <td>True if this field is a primary key</td>
            </tr><tr>
              <td scope="row"><code class="literal">IS_BLOB(flags)</code></td>
              <td>True if this field is a <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">BLOB</code></a> or
                <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">TEXT</code></a> (deprecated; test
                <code class="literal">field-&gt;type</code> instead)</td>
</tr></tbody></table>
</div>
</li><li class="listitem"><p>
          <code class="literal">unsigned int decimals</code>
        </p><p>
          The number of decimals for numeric fields, and the fractional
          seconds precision for temporal fields.
        </p></li><li class="listitem"><p>
          <code class="literal">unsigned int charsetnr</code>
        </p><p>
          An ID number that indicates the character set/collation pair
          for the field.
        </p><p>
          Normally, character values in result sets are converted to the
          character set indicated by the
          <a class="link" href="server-administration.html#sysvar_character_set_results"><code class="literal">character_set_results</code></a> system
          variable. In this case, <code class="literal">charsetnr</code>
          corresponds to the character set indicated by that variable.
          Character set conversion can be suppressed by setting
          <a class="link" href="server-administration.html#sysvar_character_set_results"><code class="literal">character_set_results</code></a> to
          <code class="literal">NULL</code>. In this case,
          <code class="literal">charsetnr</code> corresponds to the character set
          of the original table column or expression. See also
          <a class="xref" href="charset.html#charset-connection" title="10.4 Connection Character Sets and Collations">Section 10.4, “Connection Character Sets and Collations”</a>.
        </p><p>
          To distinguish between binary and nonbinary data for string
          data types, check whether the <code class="literal">charsetnr</code>
          value is 63. If so, the character set is
          <code class="literal">binary</code>, which indicates binary rather than
          nonbinary data. This enables you to distinguish
          <a class="link" href="data-types.html#binary-varbinary" title="11.4.2 The BINARY and VARBINARY Types"><code class="literal">BINARY</code></a> from
          <a class="link" href="data-types.html#char" title="11.4.1 The CHAR and VARCHAR Types"><code class="literal">CHAR</code></a>,
          <a class="link" href="data-types.html#binary-varbinary" title="11.4.2 The BINARY and VARBINARY Types"><code class="literal">VARBINARY</code></a> from
          <a class="link" href="data-types.html#char" title="11.4.1 The CHAR and VARCHAR Types"><code class="literal">VARCHAR</code></a>, and the
          <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">BLOB</code></a> types from the
          <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">TEXT</code></a> types.
        </p><p>
          <code class="literal">charsetnr</code> values are the same as those
          displayed in the <code class="literal">Id</code> column of the
          <a class="link" href="sql-syntax.html#show-collation" title="13.7.5.4 SHOW COLLATION Syntax"><code class="literal">SHOW COLLATION</code></a> statement or the
          <code class="literal">ID</code> column of the
          <code class="literal">INFORMATION_SCHEMA</code>
          <a class="link" href="information-schema.html#collations-table" title="24.2 The INFORMATION_SCHEMA COLLATIONS Table"><code class="literal">COLLATIONS</code></a> table. You can use
          those information sources to see which character set and
          collation specific <code class="literal">charsetnr</code> values
          indicate:
        </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SHOW COLLATION WHERE Id = 63;</code></strong>
+-----------+---------+----+---------+----------+---------+
| Collation | Charset | Id | Default | Compiled | Sortlen |
+-----------+---------+----+---------+----------+---------+
| binary    | binary  | 63 | Yes     | Yes      |       1 |
+-----------+---------+----+---------+----------+---------+

mysql&gt; <strong class="userinput"><code>SELECT COLLATION_NAME, CHARACTER_SET_NAME</code></strong>
    -&gt; <strong class="userinput"><code>FROM INFORMATION_SCHEMA.COLLATIONS WHERE ID = 33;</code></strong>
+-----------------+--------------------+
| COLLATION_NAME  | CHARACTER_SET_NAME |
+-----------------+--------------------+
| utf8_general_ci | utf8               |
+-----------------+--------------------+
</pre></li><li class="listitem"><p>
          <code class="literal">enum enum_field_types type</code>
        </p><p>
          The type of the field. The <code class="literal">type</code> value may
          be one of the <code class="literal">MYSQL_TYPE_</code> symbols shown in
          the following table.
</p>
<div class="informaltable">
<table summary="MYSQL_TYPE_ values and a description of each type."><col width="35%"><col width="65%"><thead><tr>
              <th scope="col">Type Value</th>
              <th scope="col">Type Description</th>
            </tr></thead><tbody><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_TINY</code></td>
              <td><a class="link" href="data-types.html#integer-types" title="11.2.1 Integer Types (Exact Value) - INTEGER, INT, SMALLINT, TINYINT, MEDIUMINT, BIGINT"><code class="literal">TINYINT</code></a> field</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_SHORT</code></td>
              <td><a class="link" href="data-types.html#integer-types" title="11.2.1 Integer Types (Exact Value) - INTEGER, INT, SMALLINT, TINYINT, MEDIUMINT, BIGINT"><code class="literal">SMALLINT</code></a> field</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_LONG</code></td>
              <td><a class="link" href="data-types.html#integer-types" title="11.2.1 Integer Types (Exact Value) - INTEGER, INT, SMALLINT, TINYINT, MEDIUMINT, BIGINT"><code class="literal">INTEGER</code></a> field</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_INT24</code></td>
              <td><a class="link" href="data-types.html#integer-types" title="11.2.1 Integer Types (Exact Value) - INTEGER, INT, SMALLINT, TINYINT, MEDIUMINT, BIGINT"><code class="literal">MEDIUMINT</code></a> field</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_LONGLONG</code></td>
              <td><a class="link" href="data-types.html#integer-types" title="11.2.1 Integer Types (Exact Value) - INTEGER, INT, SMALLINT, TINYINT, MEDIUMINT, BIGINT"><code class="literal">BIGINT</code></a> field</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_DECIMAL</code></td>
              <td><a class="link" href="data-types.html#fixed-point-types" title="11.2.2 Fixed-Point Types (Exact Value) - DECIMAL, NUMERIC"><code class="literal">DECIMAL</code></a> or
                <a class="link" href="data-types.html#fixed-point-types" title="11.2.2 Fixed-Point Types (Exact Value) - DECIMAL, NUMERIC"><code class="literal">NUMERIC</code></a> field</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_NEWDECIMAL</code></td>
              <td>Precision math <a class="link" href="data-types.html#fixed-point-types" title="11.2.2 Fixed-Point Types (Exact Value) - DECIMAL, NUMERIC"><code class="literal">DECIMAL</code></a> or
                <a class="link" href="data-types.html#fixed-point-types" title="11.2.2 Fixed-Point Types (Exact Value) - DECIMAL, NUMERIC"><code class="literal">NUMERIC</code></a></td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_FLOAT</code></td>
              <td><a class="link" href="data-types.html#floating-point-types" title="11.2.3 Floating-Point Types (Approximate Value) - FLOAT, DOUBLE"><code class="literal">FLOAT</code></a> field</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_DOUBLE</code></td>
              <td><a class="link" href="data-types.html#floating-point-types" title="11.2.3 Floating-Point Types (Approximate Value) - FLOAT, DOUBLE"><code class="literal">DOUBLE</code></a> or
                <a class="link" href="data-types.html#floating-point-types" title="11.2.3 Floating-Point Types (Approximate Value) - FLOAT, DOUBLE"><code class="literal">REAL</code></a> field</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_BIT</code></td>
              <td><a class="link" href="data-types.html#bit-type" title="11.2.4 Bit-Value Type - BIT"><code class="literal">BIT</code></a> field</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_TIMESTAMP</code></td>
              <td><a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">TIMESTAMP</code></a> field</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_DATE</code></td>
              <td><a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">DATE</code></a> field</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_TIME</code></td>
              <td><a class="link" href="data-types.html#time" title="11.3.2 The TIME Type"><code class="literal">TIME</code></a> field</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_DATETIME</code></td>
              <td><a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">DATETIME</code></a> field</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_YEAR</code></td>
              <td><a class="link" href="data-types.html#year" title="11.3.3 The YEAR Type"><code class="literal">YEAR</code></a> field</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_STRING</code></td>
              <td><a class="link" href="data-types.html#char" title="11.4.1 The CHAR and VARCHAR Types"><code class="literal">CHAR</code></a> or
                <a class="link" href="data-types.html#binary-varbinary" title="11.4.2 The BINARY and VARBINARY Types"><code class="literal">BINARY</code></a> field</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_VAR_STRING</code></td>
              <td><a class="link" href="data-types.html#char" title="11.4.1 The CHAR and VARCHAR Types"><code class="literal">VARCHAR</code></a> or
                <a class="link" href="data-types.html#binary-varbinary" title="11.4.2 The BINARY and VARBINARY Types"><code class="literal">VARBINARY</code></a> field</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_BLOB</code></td>
              <td><a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">BLOB</code></a> or
                <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">TEXT</code></a> field (use
                <code class="literal">max_length</code> to determine the maximum
                length)</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_SET</code></td>
              <td><a class="link" href="data-types.html#set" title="11.4.5 The SET Type"><code class="literal">SET</code></a> field</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_ENUM</code></td>
              <td><a class="link" href="data-types.html#enum" title="11.4.4 The ENUM Type"><code class="literal">ENUM</code></a> field</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_GEOMETRY</code></td>
              <td>Spatial field</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_NULL</code></td>
              <td><code class="literal">NULL</code>-type field</td>
</tr></tbody></table>
</div>
<p>
          The <code class="literal">MYSQL_TYPE_TIME2</code>,
          <code class="literal">MYSQL_TYPE_DATETIME2</code>, and
          <code class="literal">MYSQL_TYPE_TIMESTAMP2</code>) type codes are used
          only on the server side. Clients see the
          <code class="literal">MYSQL_TYPE_TIME</code>,
          <code class="literal">MYSQL_TYPE_DATETIME</code>, and
          <code class="literal">MYSQL_TYPE_TIMESTAMP</code> codes.
        </p><p>
          You can use the <code class="literal">IS_NUM()</code> macro to test
          whether a field has a numeric type. Pass the
          <code class="literal">type</code> value to <code class="literal">IS_NUM()</code>
          and it evaluates to TRUE if the field is numeric:
        </p><pre data-lang="c" class="programlisting">
if (IS_NUM(field-&gt;type))
    printf("Field is numeric\n");
</pre><p>
          <a class="link" href="data-types.html#enum" title="11.4.4 The ENUM Type"><code class="literal">ENUM</code></a> and
          <a class="link" href="data-types.html#set" title="11.4.5 The SET Type"><code class="literal">SET</code></a> values are returned as
          strings. For these, check that the <code class="literal">type</code>
          value is <code class="literal">MYSQL_TYPE_STRING</code> and that the
          <code class="literal">ENUM_FLAG</code> or <code class="literal">SET_FLAG</code>
          flag is set in the <code class="literal">flags</code> value.
</p></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="c-api-function-overview"></a>27.8.6 C API Function Overview</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140710575850080"></a><a class="indexterm" name="idm140710575848592"></a><p>
      The following list summarizes the functions available in the C
      API. For greater detail, see the descriptions in
      <a class="xref" href="connectors-apis.html#c-api-functions" title="27.8.7 C API Function Descriptions">Section 27.8.7, “C API Function Descriptions”</a>.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#my-init" title="27.8.12.1 my_init()"><code class="literal">my_init()</code></a>: Initialize global
          variables, and thread handler in thread-safe programs
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-affected-rows" title="27.8.7.1 mysql_affected_rows()"><code class="literal">mysql_affected_rows()</code></a>: Returns
          the number of rows changed/deleted/inserted by the last
          <a class="link" href="sql-syntax.html#update" title="13.2.11 UPDATE Syntax"><code class="literal">UPDATE</code></a>,
          <a class="link" href="sql-syntax.html#delete" title="13.2.2 DELETE Syntax"><code class="literal">DELETE</code></a>, or
          <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT</code></a> query
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-autocommit" title="27.8.7.2 mysql_autocommit()"><code class="literal">mysql_autocommit()</code></a>: Toggles
          autocommit mode on/off
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-change-user" title="27.8.7.3 mysql_change_user()"><code class="literal">mysql_change_user()</code></a>: Changes
          user and database on an open connection
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-character-set-name" title="27.8.7.4 mysql_character_set_name()"><code class="literal">mysql_character_set_name()</code></a>:
          Return default character set name for current connection
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-client-find-plugin" title="27.8.14.1 mysql_client_find_plugin()"><code class="literal">mysql_client_find_plugin()</code></a>:
          Return pointer to plugin
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-client-register-plugin" title="27.8.14.2 mysql_client_register_plugin()"><code class="literal">mysql_client_register_plugin()</code></a>:
          Register a plugin
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-close" title="27.8.7.5 mysql_close()"><code class="literal">mysql_close()</code></a>: Closes a server
          connection
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-commit" title="27.8.7.6 mysql_commit()"><code class="literal">mysql_commit()</code></a>: Commits the
          transaction
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-connect" title="27.8.7.7 mysql_connect()"><code class="literal">mysql_connect()</code></a>: Connects to a
          MySQL server (this function is deprecated; use
          <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a> instead)
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-create-db" title="27.8.7.8 mysql_create_db()"><code class="literal">mysql_create_db()</code></a>: Creates a
          database (this function is deprecated; use the SQL statement
          <a class="link" href="sql-syntax.html#create-database" title="13.1.11 CREATE DATABASE Syntax"><code class="literal">CREATE DATABASE</code></a> instead)
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-data-seek" title="27.8.7.9 mysql_data_seek()"><code class="literal">mysql_data_seek()</code></a>: Seeks to an
          arbitrary row number in a query result set
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-debug" title="27.8.7.10 mysql_debug()"><code class="literal">mysql_debug()</code></a>: Does a
          <code class="literal">DBUG_PUSH</code> with the given string
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-drop-db" title="27.8.7.11 mysql_drop_db()"><code class="literal">mysql_drop_db()</code></a>: Drops a
          database (this function is deprecated; use the SQL statement
          <a class="link" href="sql-syntax.html#drop-database" title="13.1.22 DROP DATABASE Syntax"><code class="literal">DROP DATABASE</code></a> instead)
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-dump-debug-info" title="27.8.7.12 mysql_dump_debug_info()"><code class="literal">mysql_dump_debug_info()</code></a>: Makes
          the server write debug information to the log
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-eof" title="27.8.7.13 mysql_eof()"><code class="literal">mysql_eof()</code></a>: Determines
          whether the last row of a result set has been read (this
          function is deprecated;
          <a class="link" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()"><code class="literal">mysql_errno()</code></a> or
          <a class="link" href="connectors-apis.html#mysql-error" title="27.8.7.15 mysql_error()"><code class="literal">mysql_error()</code></a> may be used
          instead)
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()"><code class="literal">mysql_errno()</code></a>: Returns the
          error number for the most recently invoked MySQL function
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-error" title="27.8.7.15 mysql_error()"><code class="literal">mysql_error()</code></a>: Returns the
          error message for the most recently invoked MySQL function
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-escape-string" title="27.8.7.16 mysql_escape_string()"><code class="literal">mysql_escape_string()</code></a>: Escapes
          special characters in a string for use in an SQL statement
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-fetch-field" title="27.8.7.17 mysql_fetch_field()"><code class="literal">mysql_fetch_field()</code></a>: Returns
          the type of the next table field
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-fetch-field-direct" title="27.8.7.18 mysql_fetch_field_direct()"><code class="literal">mysql_fetch_field_direct()</code></a>:
          Returns the type of a table field, given a field number
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-fetch-fields" title="27.8.7.19 mysql_fetch_fields()"><code class="literal">mysql_fetch_fields()</code></a>: Returns
          an array of all field structures
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-fetch-lengths" title="27.8.7.20 mysql_fetch_lengths()"><code class="literal">mysql_fetch_lengths()</code></a>: Returns
          the lengths of all columns in the current row
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-fetch-row" title="27.8.7.21 mysql_fetch_row()"><code class="literal">mysql_fetch_row()</code></a>: Fetches the
          next row from the result set
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-field-count" title="27.8.7.22 mysql_field_count()"><code class="literal">mysql_field_count()</code></a>: Returns
          the number of result columns for the most recent statement
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-field-seek" title="27.8.7.23 mysql_field_seek()"><code class="literal">mysql_field_seek()</code></a>: Puts the
          column cursor on a specified column
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-field-tell" title="27.8.7.24 mysql_field_tell()"><code class="literal">mysql_field_tell()</code></a>: Returns
          the position of the field cursor used for the last
          <a class="link" href="connectors-apis.html#mysql-fetch-field" title="27.8.7.17 mysql_fetch_field()"><code class="literal">mysql_fetch_field()</code></a>
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-free-result" title="27.8.7.25 mysql_free_result()"><code class="literal">mysql_free_result()</code></a>: Frees
          memory used by a result set
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-get-character-set-info" title="27.8.7.26 mysql_get_character_set_info()"><code class="literal">mysql_get_character_set_info()</code></a>:
          Return information about default character set
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-get-client-info" title="27.8.7.27 mysql_get_client_info()"><code class="literal">mysql_get_client_info()</code></a>:
          Returns client version information as a string
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-get-client-version" title="27.8.7.28 mysql_get_client_version()"><code class="literal">mysql_get_client_version()</code></a>:
          Returns client version information as an integer
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-get-host-info" title="27.8.7.29 mysql_get_host_info()"><code class="literal">mysql_get_host_info()</code></a>: Returns
          a string describing the connection
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-get-option" title="27.8.7.30 mysql_get_option()"><code class="literal">mysql_get_option()</code></a>: Returns
          the value of a <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a>
          option
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-get-proto-info" title="27.8.7.31 mysql_get_proto_info()"><code class="literal">mysql_get_proto_info()</code></a>:
          Returns the protocol version used by the connection
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-get-server-info" title="27.8.7.32 mysql_get_server_info()"><code class="literal">mysql_get_server_info()</code></a>:
          Returns the server version number
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-get-server-version" title="27.8.7.33 mysql_get_server_version()"><code class="literal">mysql_get_server_version()</code></a>:
          Returns version number of server as an integer
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-get-ssl-cipher" title="27.8.7.34 mysql_get_ssl_cipher()"><code class="literal">mysql_get_ssl_cipher()</code></a>: Return
          current SSL cipher
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-hex-string" title="27.8.7.35 mysql_hex_string()"><code class="literal">mysql_hex_string()</code></a>: Encode
          string in hexadecimal format
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-info" title="27.8.7.36 mysql_info()"><code class="literal">mysql_info()</code></a>: Returns
          information about the most recently executed query
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-init" title="27.8.7.37 mysql_init()"><code class="literal">mysql_init()</code></a>: Gets or
          initializes a <code class="literal">MYSQL</code> structure
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-insert-id" title="27.8.7.38 mysql_insert_id()"><code class="literal">mysql_insert_id()</code></a>: Returns the
          ID generated for an <code class="literal">AUTO_INCREMENT</code> column
          by the previous query
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-kill" title="27.8.7.39 mysql_kill()"><code class="literal">mysql_kill()</code></a>: Kills a given
          thread
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-library-end" title="27.8.7.40 mysql_library_end()"><code class="literal">mysql_library_end()</code></a>: Finalize
          the MySQL C API library
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a>:
          Initialize the MySQL C API library
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-list-dbs" title="27.8.7.42 mysql_list_dbs()"><code class="literal">mysql_list_dbs()</code></a>: Returns
          database names matching a simple regular expression
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-list-fields" title="27.8.7.43 mysql_list_fields()"><code class="literal">mysql_list_fields()</code></a>: Returns
          field names matching a simple regular expression
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-list-processes" title="27.8.7.44 mysql_list_processes()"><code class="literal">mysql_list_processes()</code></a>:
          Returns a list of the current server threads
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-list-tables" title="27.8.7.45 mysql_list_tables()"><code class="literal">mysql_list_tables()</code></a>: Returns
          table names matching a simple regular expression
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-load-plugin" title="27.8.14.3 mysql_load_plugin()"><code class="literal">mysql_load_plugin()</code></a>: Load a
          plugin
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-load-plugin-v" title="27.8.14.4 mysql_load_plugin_v()"><code class="literal">mysql_load_plugin_v()</code></a>: Load a
          plugin
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-more-results" title="27.8.7.46 mysql_more_results()"><code class="literal">mysql_more_results()</code></a>: Checks
          whether any more results exist
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-next-result" title="27.8.7.47 mysql_next_result()"><code class="literal">mysql_next_result()</code></a>:
          Returns/initiates the next result in multiple-result
          executions
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-num-fields" title="27.8.7.48 mysql_num_fields()"><code class="literal">mysql_num_fields()</code></a>: Returns
          the number of columns in a result set
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-num-rows" title="27.8.7.49 mysql_num_rows()"><code class="literal">mysql_num_rows()</code></a>: Returns the
          number of rows in a result set
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a>: Sets connect
          options for
          <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a>
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-options4" title="27.8.7.51 mysql_options4()"><code class="literal">mysql_options4()</code></a>: Sets connect
          options for
          <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a>
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-ping" title="27.8.7.52 mysql_ping()"><code class="literal">mysql_ping()</code></a>: Checks whether
          the connection to the server is working, reconnecting as
          necessary
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-plugin-options" title="27.8.14.5 mysql_plugin_options()"><code class="literal">mysql_plugin_options()</code></a>: Set a
          plugin option
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a>: Executes an SQL
          query specified as a null-terminated string
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a>: Connects
          to a MySQL server
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-real-escape-string" title="27.8.7.55 mysql_real_escape_string()"><code class="literal">mysql_real_escape_string()</code></a>:
          Escapes special characters in a string for use in an SQL
          statement, taking into account the current character set of
          the connection
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-real-escape-string-quote" title="27.8.7.56 mysql_real_escape_string_quote()"><code class="literal">mysql_real_escape_string_quote()</code></a>:
          Escapes special characters in a string for use in an SQL
          statement, taking into account the current character set of
          the connection and the quoting context
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-real-query" title="27.8.7.57 mysql_real_query()"><code class="literal">mysql_real_query()</code></a>: Executes
          an SQL query specified as a counted string
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-refresh" title="27.8.7.58 mysql_refresh()"><code class="literal">mysql_refresh()</code></a>: Flush or
          reset tables and caches
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-reload" title="27.8.7.59 mysql_reload()"><code class="literal">mysql_reload()</code></a>: Tells the
          server to reload the grant tables
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-reset-connection" title="27.8.7.60 mysql_reset_connection()"><code class="literal">mysql_reset_connection()</code></a>:
          Reset connection to clear session state
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-rollback" title="27.8.7.61 mysql_rollback()"><code class="literal">mysql_rollback()</code></a>: Rolls back
          the transaction
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-row-seek" title="27.8.7.62 mysql_row_seek()"><code class="literal">mysql_row_seek()</code></a>: Seeks to a
          row offset in a result set, using value returned from
          <a class="link" href="connectors-apis.html#mysql-row-tell" title="27.8.7.63 mysql_row_tell()"><code class="literal">mysql_row_tell()</code></a>
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-row-tell" title="27.8.7.63 mysql_row_tell()"><code class="literal">mysql_row_tell()</code></a>: Returns the
          row cursor position
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-select-db" title="27.8.7.64 mysql_select_db()"><code class="literal">mysql_select_db()</code></a>: Selects a
          database
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-server-end" title="27.8.13.1 mysql_server_end()"><code class="literal">mysql_server_end()</code></a>: Finalize
          the MySQL C API library
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-server-init" title="27.8.13.2 mysql_server_init()"><code class="literal">mysql_server_init()</code></a>:
          Initialize the MySQL C API library
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-session-track-get-first" title="27.8.7.65 mysql_session_track_get_first()"><code class="literal">mysql_session_track_get_first()</code></a>:
          Get first part of session state-change information
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-session-track-get-next" title="27.8.7.66 mysql_session_track_get_next()"><code class="literal">mysql_session_track_get_next()</code></a>:
          Get next part of session state-change information
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-set-character-set" title="27.8.7.67 mysql_set_character_set()"><code class="literal">mysql_set_character_set()</code></a>: Set
          default character set for current connection
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-set-local-infile-default" title="27.8.7.68 mysql_set_local_infile_default()"><code class="literal">mysql_set_local_infile_default()</code></a>:
          Set the <a class="link" href="sql-syntax.html#load-data" title="13.2.6 LOAD DATA INFILE Syntax"><code class="literal">LOAD DATA
          LOCAL INFILE</code></a> handler callbacks to their default
          values
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-set-local-infile-handler" title="27.8.7.69 mysql_set_local_infile_handler()"><code class="literal">mysql_set_local_infile_handler()</code></a>:
          Install application-specific
          <a class="link" href="sql-syntax.html#load-data" title="13.2.6 LOAD DATA INFILE Syntax"><code class="literal">LOAD DATA LOCAL
          INFILE</code></a> handler callbacks
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-set-server-option" title="27.8.7.70 mysql_set_server_option()"><code class="literal">mysql_set_server_option()</code></a>:
          Sets an option for the connection (like
          <code class="literal">multi-statements</code>)
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-sqlstate" title="27.8.7.72 mysql_sqlstate()"><code class="literal">mysql_sqlstate()</code></a>: Returns the
          SQLSTATE error code for the last error
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-shutdown" title="27.8.7.71 mysql_shutdown()"><code class="literal">mysql_shutdown()</code></a>: Shuts down
          the database server
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-ssl-set" title="27.8.7.73 mysql_ssl_set()"><code class="literal">mysql_ssl_set()</code></a>: Prepare to
          establish SSL connection to server
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stat" title="27.8.7.74 mysql_stat()"><code class="literal">mysql_stat()</code></a>: Returns the
          server status as a string
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a>:
          Retrieves a complete result set to the client
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-thread-end" title="27.8.12.2 mysql_thread_end()"><code class="literal">mysql_thread_end()</code></a>: Finalize
          thread handler
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-thread-id" title="27.8.7.76 mysql_thread_id()"><code class="literal">mysql_thread_id()</code></a>: Returns the
          current thread ID
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-thread-init" title="27.8.12.3 mysql_thread_init()"><code class="literal">mysql_thread_init()</code></a>:
          Initialize thread handler
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-thread-safe" title="27.8.12.4 mysql_thread_safe()"><code class="literal">mysql_thread_safe()</code></a>: Returns 1
          if the clients are compiled as thread-safe
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a>: Initiates
          a row-by-row result set retrieval
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-warning-count" title="27.8.7.78 mysql_warning_count()"><code class="literal">mysql_warning_count()</code></a>: Returns
          the warning count for the previous SQL statement
</p></li></ul>
</div>
<p>
      Application programs should use this general outline for
      interacting with MySQL:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
          Initialize the MySQL client library by calling
          <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a>. This
          function exists in both the <code class="literal">libmysqlclient</code>
          C client library and the <code class="literal">libmysqld</code> embedded
          server library, so it is used whether you build a regular
          client program by linking with the
          <code class="option">-libmysqlclient</code> flag, or an embedded server
          application by linking with the <code class="option">-libmysqld</code>
          flag.
        </p></li><li class="listitem"><p>
          Initialize a connection handler by calling
          <a class="link" href="connectors-apis.html#mysql-init" title="27.8.7.37 mysql_init()"><code class="literal">mysql_init()</code></a> and connect to
          the server by calling
          <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a>.
        </p></li><li class="listitem"><p>
          Issue SQL statements and process their results. (The following
          discussion provides more information about how to do this.)
        </p></li><li class="listitem"><p>
          Close the connection to the MySQL server by calling
          <a class="link" href="connectors-apis.html#mysql-close" title="27.8.7.5 mysql_close()"><code class="literal">mysql_close()</code></a>.
        </p></li><li class="listitem"><p>
          End use of the MySQL client library by calling
          <a class="link" href="connectors-apis.html#mysql-library-end" title="27.8.7.40 mysql_library_end()"><code class="literal">mysql_library_end()</code></a>.
</p></li></ol>
</div>
<p>
      The purpose of calling
      <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a> and
      <a class="link" href="connectors-apis.html#mysql-library-end" title="27.8.7.40 mysql_library_end()"><code class="literal">mysql_library_end()</code></a> is to provide
      proper initialization and finalization of the MySQL client
      library. For applications that are linked with the client library,
      they provide improved memory management. If you do not call
      <a class="link" href="connectors-apis.html#mysql-library-end" title="27.8.7.40 mysql_library_end()"><code class="literal">mysql_library_end()</code></a>, a block of
      memory remains allocated. (This does not increase the amount of
      memory used by the application, but some memory leak detectors
      will complain about it.) For applications that are linked with the
      embedded server, these calls start and stop the server.
    </p><p>
      In a nonmulti-threaded environment, the call to
      <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a> may be
      omitted, because <a class="link" href="connectors-apis.html#mysql-init" title="27.8.7.37 mysql_init()"><code class="literal">mysql_init()</code></a> will
      invoke it automatically as necessary. However,
      <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a> is not
      thread-safe in a multi-threaded environment, and thus neither is
      <a class="link" href="connectors-apis.html#mysql-init" title="27.8.7.37 mysql_init()"><code class="literal">mysql_init()</code></a>, which calls
      <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a>. You must
      either call <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a>
      prior to spawning any threads, or else use a mutex to protect the
      call, whether you invoke
      <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a> or indirectly
      through <a class="link" href="connectors-apis.html#mysql-init" title="27.8.7.37 mysql_init()"><code class="literal">mysql_init()</code></a>. This should
      be done prior to any other client library call.
    </p><p>
      To connect to the server, call
      <a class="link" href="connectors-apis.html#mysql-init" title="27.8.7.37 mysql_init()"><code class="literal">mysql_init()</code></a> to initialize a
      connection handler, then call
      <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a> with that
      handler (along with other information such as the host name, user
      name, and password). Upon connection,
      <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a> sets the
      <code class="literal">reconnect</code> flag (part of the
      <code class="literal">MYSQL</code> structure) to a value of
      <code class="literal">1</code> in versions of the API older than 5.0.3, or
      <code class="literal">0</code> in newer versions. A value of
      <code class="literal">1</code> for this flag indicates that if a statement
      cannot be performed because of a lost connection, to try
      reconnecting to the server before giving up. You can use the
      <code class="literal">MYSQL_OPT_RECONNECT</code> option to
      <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> to control
      reconnection behavior. When you are done with the connection, call
      <a class="link" href="connectors-apis.html#mysql-close" title="27.8.7.5 mysql_close()"><code class="literal">mysql_close()</code></a> to terminate it.
    </p><p>
      While a connection is active, the client may send SQL statements
      to the server using <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a>
      or <a class="link" href="connectors-apis.html#mysql-real-query" title="27.8.7.57 mysql_real_query()"><code class="literal">mysql_real_query()</code></a>. The
      difference between the two is that
      <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a> expects the query to
      be specified as a null-terminated string whereas
      <a class="link" href="connectors-apis.html#mysql-real-query" title="27.8.7.57 mysql_real_query()"><code class="literal">mysql_real_query()</code></a> expects a
      counted string. If the string contains binary data (which may
      include null bytes), you must use
      <a class="link" href="connectors-apis.html#mysql-real-query" title="27.8.7.57 mysql_real_query()"><code class="literal">mysql_real_query()</code></a>.
    </p><p>
      For each non-<a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a> query (for
      example, <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT</code></a>,
      <a class="link" href="sql-syntax.html#update" title="13.2.11 UPDATE Syntax"><code class="literal">UPDATE</code></a>,
      <a class="link" href="sql-syntax.html#delete" title="13.2.2 DELETE Syntax"><code class="literal">DELETE</code></a>), you can find out how many
      rows were changed (affected) by calling
      <a class="link" href="connectors-apis.html#mysql-affected-rows" title="27.8.7.1 mysql_affected_rows()"><code class="literal">mysql_affected_rows()</code></a>.
    </p><p>
      For <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a> queries, you retrieve
      the selected rows as a result set. (Note that some statements are
      <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a>-like in that they return
      rows. These include <a class="link" href="sql-syntax.html#show" title="13.7.5 SHOW Syntax"><code class="literal">SHOW</code></a>,
      <a class="link" href="sql-syntax.html#describe" title="13.8.1 DESCRIBE Syntax"><code class="literal">DESCRIBE</code></a>, and
      <a class="link" href="sql-syntax.html#explain" title="13.8.2 EXPLAIN Syntax"><code class="literal">EXPLAIN</code></a>. Treat these statements the
      same way as <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a> statements.)
    </p><p>
      There are two ways for a client to process result sets. One way is
      to retrieve the entire result set all at once by calling
      <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a>. This
      function acquires from the server all the rows returned by the
      query and stores them in the client. The second way is for the
      client to initiate a row-by-row result set retrieval by calling
      <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a>. This function
      initializes the retrieval, but does not actually get any rows from
      the server.
    </p><p>
      In both cases, you access rows by calling
      <a class="link" href="connectors-apis.html#mysql-fetch-row" title="27.8.7.21 mysql_fetch_row()"><code class="literal">mysql_fetch_row()</code></a>. With
      <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a>,
      <a class="link" href="connectors-apis.html#mysql-fetch-row" title="27.8.7.21 mysql_fetch_row()"><code class="literal">mysql_fetch_row()</code></a> accesses rows
      that have previously been fetched from the server. With
      <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a>,
      <a class="link" href="connectors-apis.html#mysql-fetch-row" title="27.8.7.21 mysql_fetch_row()"><code class="literal">mysql_fetch_row()</code></a> actually
      retrieves the row from the server. Information about the size of
      the data in each row is available by calling
      <a class="link" href="connectors-apis.html#mysql-fetch-lengths" title="27.8.7.20 mysql_fetch_lengths()"><code class="literal">mysql_fetch_lengths()</code></a>.
    </p><p>
      After you are done with a result set, call
      <a class="link" href="connectors-apis.html#mysql-free-result" title="27.8.7.25 mysql_free_result()"><code class="literal">mysql_free_result()</code></a> to free the
      memory used for it.
    </p><p>
      The two retrieval mechanisms are complementary. Choose the
      approach that is most appropriate for each client application. In
      practice, clients tend to use
      <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a> more
      commonly.
    </p><p>
      An advantage of
      <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a> is that
      because the rows have all been fetched to the client, you not only
      can access rows sequentially, you can move back and forth in the
      result set using <a class="link" href="connectors-apis.html#mysql-data-seek" title="27.8.7.9 mysql_data_seek()"><code class="literal">mysql_data_seek()</code></a>
      or <a class="link" href="connectors-apis.html#mysql-row-seek" title="27.8.7.62 mysql_row_seek()"><code class="literal">mysql_row_seek()</code></a> to change the
      current row position within the result set. You can also find out
      how many rows there are by calling
      <a class="link" href="connectors-apis.html#mysql-num-rows" title="27.8.7.49 mysql_num_rows()"><code class="literal">mysql_num_rows()</code></a>. On the other
      hand, the memory requirements for
      <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a> may be very
      high for large result sets and you are more likely to encounter
      out-of-memory conditions.
    </p><p>
      An advantage of <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a>
      is that the client requires less memory for the result set because
      it maintains only one row at a time (and because there is less
      allocation overhead,
      <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a> can be faster).
      Disadvantages are that you must process each row quickly to avoid
      tying up the server, you do not have random access to rows within
      the result set (you can only access rows sequentially), and the
      number of rows in the result set is unknown until you have
      retrieved them all. Furthermore, you <span class="emphasis"><em>must</em></span>
      retrieve all the rows even if you determine in mid-retrieval that
      you've found the information you were looking for.
    </p><p>
      The API makes it possible for clients to respond appropriately to
      statements (retrieving rows only as necessary) without knowing
      whether the statement is a <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a>.
      You can do this by calling
      <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a> after each
      <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a> (or
      <a class="link" href="connectors-apis.html#mysql-real-query" title="27.8.7.57 mysql_real_query()"><code class="literal">mysql_real_query()</code></a>). If the result
      set call succeeds, the statement was a
      <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a> and you can read the rows.
      If the result set call fails, call
      <a class="link" href="connectors-apis.html#mysql-field-count" title="27.8.7.22 mysql_field_count()"><code class="literal">mysql_field_count()</code></a> to determine
      whether a result was actually to be expected. If
      <a class="link" href="connectors-apis.html#mysql-field-count" title="27.8.7.22 mysql_field_count()"><code class="literal">mysql_field_count()</code></a> returns zero,
      the statement returned no data (indicating that it was an
      <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT</code></a>,
      <a class="link" href="sql-syntax.html#update" title="13.2.11 UPDATE Syntax"><code class="literal">UPDATE</code></a>,
      <a class="link" href="sql-syntax.html#delete" title="13.2.2 DELETE Syntax"><code class="literal">DELETE</code></a>, and so forth), and was not
      expected to return rows. If
      <a class="link" href="connectors-apis.html#mysql-field-count" title="27.8.7.22 mysql_field_count()"><code class="literal">mysql_field_count()</code></a> is nonzero,
      the statement should have returned rows, but did not. This
      indicates that the statement was a
      <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a> that failed. See the
      description for
      <a class="link" href="connectors-apis.html#mysql-field-count" title="27.8.7.22 mysql_field_count()"><code class="literal">mysql_field_count()</code></a> for an example
      of how this can be done.
    </p><p>
      Both <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a> and
      <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a> enable you to
      obtain information about the fields that make up the result set
      (the number of fields, their names and types, and so forth). You
      can access field information sequentially within the row by
      calling <a class="link" href="connectors-apis.html#mysql-fetch-field" title="27.8.7.17 mysql_fetch_field()"><code class="literal">mysql_fetch_field()</code></a>
      repeatedly, or by field number within the row by calling
      <a class="link" href="connectors-apis.html#mysql-fetch-field-direct" title="27.8.7.18 mysql_fetch_field_direct()"><code class="literal">mysql_fetch_field_direct()</code></a>. The
      current field cursor position may be changed by calling
      <a class="link" href="connectors-apis.html#mysql-field-seek" title="27.8.7.23 mysql_field_seek()"><code class="literal">mysql_field_seek()</code></a>. Setting the
      field cursor affects subsequent calls to
      <a class="link" href="connectors-apis.html#mysql-fetch-field" title="27.8.7.17 mysql_fetch_field()"><code class="literal">mysql_fetch_field()</code></a>. You can also
      get information for fields all at once by calling
      <a class="link" href="connectors-apis.html#mysql-fetch-fields" title="27.8.7.19 mysql_fetch_fields()"><code class="literal">mysql_fetch_fields()</code></a>.
    </p><p>
      For detecting and reporting errors, MySQL provides access to error
      information by means of the
      <a class="link" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()"><code class="literal">mysql_errno()</code></a> and
      <a class="link" href="connectors-apis.html#mysql-error" title="27.8.7.15 mysql_error()"><code class="literal">mysql_error()</code></a> functions. These
      return the error code or error message for the most recently
      invoked function that can succeed or fail, enabling you to
      determine when an error occurred and what it was.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="c-api-functions"></a>27.8.7 C API Function Descriptions</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="connectors-apis.html#mysql-affected-rows">27.8.7.1 mysql_affected_rows()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-autocommit">27.8.7.2 mysql_autocommit()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-change-user">27.8.7.3 mysql_change_user()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-character-set-name">27.8.7.4 mysql_character_set_name()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-close">27.8.7.5 mysql_close()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-commit">27.8.7.6 mysql_commit()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-connect">27.8.7.7 mysql_connect()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-create-db">27.8.7.8 mysql_create_db()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-data-seek">27.8.7.9 mysql_data_seek()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-debug">27.8.7.10 mysql_debug()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-drop-db">27.8.7.11 mysql_drop_db()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-dump-debug-info">27.8.7.12 mysql_dump_debug_info()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-eof">27.8.7.13 mysql_eof()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-errno">27.8.7.14 mysql_errno()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-error">27.8.7.15 mysql_error()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-escape-string">27.8.7.16 mysql_escape_string()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-fetch-field">27.8.7.17 mysql_fetch_field()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-fetch-field-direct">27.8.7.18 mysql_fetch_field_direct()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-fetch-fields">27.8.7.19 mysql_fetch_fields()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-fetch-lengths">27.8.7.20 mysql_fetch_lengths()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-fetch-row">27.8.7.21 mysql_fetch_row()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-field-count">27.8.7.22 mysql_field_count()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-field-seek">27.8.7.23 mysql_field_seek()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-field-tell">27.8.7.24 mysql_field_tell()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-free-result">27.8.7.25 mysql_free_result()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-get-character-set-info">27.8.7.26 mysql_get_character_set_info()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-get-client-info">27.8.7.27 mysql_get_client_info()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-get-client-version">27.8.7.28 mysql_get_client_version()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-get-host-info">27.8.7.29 mysql_get_host_info()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-get-option">27.8.7.30 mysql_get_option()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-get-proto-info">27.8.7.31 mysql_get_proto_info()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-get-server-info">27.8.7.32 mysql_get_server_info()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-get-server-version">27.8.7.33 mysql_get_server_version()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-get-ssl-cipher">27.8.7.34 mysql_get_ssl_cipher()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-hex-string">27.8.7.35 mysql_hex_string()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-info">27.8.7.36 mysql_info()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-init">27.8.7.37 mysql_init()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-insert-id">27.8.7.38 mysql_insert_id()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-kill">27.8.7.39 mysql_kill()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-library-end">27.8.7.40 mysql_library_end()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-library-init">27.8.7.41 mysql_library_init()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-list-dbs">27.8.7.42 mysql_list_dbs()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-list-fields">27.8.7.43 mysql_list_fields()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-list-processes">27.8.7.44 mysql_list_processes()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-list-tables">27.8.7.45 mysql_list_tables()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-more-results">27.8.7.46 mysql_more_results()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-next-result">27.8.7.47 mysql_next_result()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-num-fields">27.8.7.48 mysql_num_fields()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-num-rows">27.8.7.49 mysql_num_rows()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-options">27.8.7.50 mysql_options()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-options4">27.8.7.51 mysql_options4()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-ping">27.8.7.52 mysql_ping()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-query">27.8.7.53 mysql_query()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-real-connect">27.8.7.54 mysql_real_connect()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-real-escape-string">27.8.7.55 mysql_real_escape_string()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-real-escape-string-quote">27.8.7.56 mysql_real_escape_string_quote()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-real-query">27.8.7.57 mysql_real_query()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-refresh">27.8.7.58 mysql_refresh()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-reload">27.8.7.59 mysql_reload()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-reset-connection">27.8.7.60 mysql_reset_connection()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-rollback">27.8.7.61 mysql_rollback()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-row-seek">27.8.7.62 mysql_row_seek()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-row-tell">27.8.7.63 mysql_row_tell()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-select-db">27.8.7.64 mysql_select_db()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-session-track-get-first">27.8.7.65 mysql_session_track_get_first()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-session-track-get-next">27.8.7.66 mysql_session_track_get_next()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-set-character-set">27.8.7.67 mysql_set_character_set()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-set-local-infile-default">27.8.7.68 mysql_set_local_infile_default()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-set-local-infile-handler">27.8.7.69 mysql_set_local_infile_handler()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-set-server-option">27.8.7.70 mysql_set_server_option()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-shutdown">27.8.7.71 mysql_shutdown()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-sqlstate">27.8.7.72 mysql_sqlstate()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-ssl-set">27.8.7.73 mysql_ssl_set()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stat">27.8.7.74 mysql_stat()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-store-result">27.8.7.75 mysql_store_result()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-thread-id">27.8.7.76 mysql_thread_id()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-use-result">27.8.7.77 mysql_use_result()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-warning-count">27.8.7.78 mysql_warning_count()</a></span></dt></dl>
</div>
<p>
      In the descriptions here, a parameter or return value of
      <code class="literal">NULL</code> means <code class="literal">NULL</code> in the sense
      of the C programming language, not a MySQL <code class="literal">NULL</code>
      value.
    </p><p>
      Functions that return a value generally return a pointer or an
      integer. Unless specified otherwise, functions returning a pointer
      return a non-<code class="literal">NULL</code> value to indicate success or
      a <code class="literal">NULL</code> value to indicate an error, and
      functions returning an integer return zero to indicate success or
      nonzero to indicate an error. Note that <span class="quote">“<span class="quote">nonzero</span>”</span>
      means just that. Unless the function description says otherwise,
      do not test against a value other than zero:
    </p><pre data-lang="c" class="programlisting">
if (result)                   /* correct */
    ... error ...

if (result &lt; 0)               /* incorrect */
    ... error ...

if (result == -1)             /* incorrect */
    ... error ...
</pre><p>
      When a function returns an error, the
      <span class="bold"><strong>Errors</strong></span> subsection of the function
      description lists the possible types of errors. You can find out
      which of these occurred by calling
      <a class="link" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()"><code class="literal">mysql_errno()</code></a>. A string
      representation of the error may be obtained by calling
      <a class="link" href="connectors-apis.html#mysql-error" title="27.8.7.15 mysql_error()"><code class="literal">mysql_error()</code></a>.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-affected-rows"></a>27.8.7.1 mysql_affected_rows()</h4>
</div>
</div>
</div>
<a class="indexterm" name="idm140710575501472"></a><p>
        <code class="literal">my_ulonglong mysql_affected_rows(MYSQL
        *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-affected-rows-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          <a class="link" href="connectors-apis.html#mysql-affected-rows" title="27.8.7.1 mysql_affected_rows()"><code class="literal">mysql_affected_rows()</code></a> may be
          called immediately after executing a statement with
          <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a> or
          <a class="link" href="connectors-apis.html#mysql-real-query" title="27.8.7.57 mysql_real_query()"><code class="literal">mysql_real_query()</code></a>. It returns
          the number of rows changed, deleted, or inserted by the last
          statement if it was an <a class="link" href="sql-syntax.html#update" title="13.2.11 UPDATE Syntax"><code class="literal">UPDATE</code></a>,
          <a class="link" href="sql-syntax.html#delete" title="13.2.2 DELETE Syntax"><code class="literal">DELETE</code></a>, or
          <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT</code></a>. For
          <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a> statements,
          <a class="link" href="connectors-apis.html#mysql-affected-rows" title="27.8.7.1 mysql_affected_rows()"><code class="literal">mysql_affected_rows()</code></a> works
          like <a class="link" href="connectors-apis.html#mysql-num-rows" title="27.8.7.49 mysql_num_rows()"><code class="literal">mysql_num_rows()</code></a>.
        </p><p>
          For <a class="link" href="sql-syntax.html#update" title="13.2.11 UPDATE Syntax"><code class="literal">UPDATE</code></a> statements, the
          affected-rows value by default is the number of rows actually
          changed. If you specify the
          <code class="literal">CLIENT_FOUND_ROWS</code> flag to
          <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a> when
          connecting to <a class="link" href="programs.html#mysqld" title="4.3.1 mysqld — The MySQL Server"><span class="command"><strong>mysqld</strong></span></a>, the affected-rows
          value is the number of rows <span class="quote">“<span class="quote">found</span>”</span>; that is,
          matched by the <code class="literal">WHERE</code> clause.
        </p><p>
          For <a class="link" href="sql-syntax.html#replace" title="13.2.8 REPLACE Syntax"><code class="literal">REPLACE</code></a> statements, the
          affected-rows value is 2 if the new row replaced an old row,
          because in this case, one row was inserted after the duplicate
          was deleted.
        </p><p>
          For
          <a class="link" href="sql-syntax.html#insert-on-duplicate" title="13.2.5.2 INSERT ... ON DUPLICATE KEY UPDATE Syntax"><code class="literal">INSERT
          ... ON DUPLICATE KEY UPDATE</code></a> statements, the
          affected-rows value per row is 1 if the row is inserted as a
          new row, 2 if an existing row is updated, and 0 if an existing
          row is set to its current values. If you specify the
          <code class="literal">CLIENT_FOUND_ROWS</code> flag, the affected-rows
          value is 1 (not 0) if an existing row is set to its current
          values.
        </p><p>
          Following a <a class="link" href="sql-syntax.html#call" title="13.2.1 CALL Syntax"><code class="literal">CALL</code></a> statement for
          a stored procedure,
          <a class="link" href="connectors-apis.html#mysql-affected-rows" title="27.8.7.1 mysql_affected_rows()"><code class="literal">mysql_affected_rows()</code></a> returns
          the value that it would return for the last statement executed
          within the procedure, or <code class="literal">0</code> if that
          statement would return <code class="literal">-1</code>. Within the
          procedure, you can use
          <a class="link" href="functions.html#function_row-count"><code class="literal">ROW_COUNT()</code></a> at the SQL level to
          obtain the affected-rows value for individual statements.
        </p><p>
          In MySQL 5.7,
          <a class="link" href="connectors-apis.html#mysql-affected-rows" title="27.8.7.1 mysql_affected_rows()"><code class="literal">mysql_affected_rows()</code></a> returns
          a meaningful value for a wider range of statements. For
          details, see the description for
          <a class="link" href="functions.html#function_row-count"><code class="literal">ROW_COUNT()</code></a> in
          <a class="xref" href="functions.html#information-functions" title="12.14 Information Functions">Section 12.14, “Information Functions”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-affected-rows-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          An integer greater than zero indicates the number of rows
          affected or retrieved. Zero indicates that no records were
          updated for an <a class="link" href="sql-syntax.html#update" title="13.2.11 UPDATE Syntax"><code class="literal">UPDATE</code></a>
          statement, no rows matched the <code class="literal">WHERE</code> clause
          in the query or that no query has yet been executed. -1
          indicates that the query returned an error or that, for a
          <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a> query,
          <a class="link" href="connectors-apis.html#mysql-affected-rows" title="27.8.7.1 mysql_affected_rows()"><code class="literal">mysql_affected_rows()</code></a> was
          called prior to calling
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a>.
        </p><p>
          Because <a class="link" href="connectors-apis.html#mysql-affected-rows" title="27.8.7.1 mysql_affected_rows()"><code class="literal">mysql_affected_rows()</code></a>
          returns an unsigned value, you can check for -1 by comparing
          the return value to <code class="literal">(my_ulonglong)-1</code> (or to
          <code class="literal">(my_ulonglong)~0</code>, which is equivalent).
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-affected-rows-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-affected-rows-example"></a>Example</h5>

</div>

</div>

</div>
<pre data-lang="c" class="programlisting">
char *stmt = "UPDATE products SET cost=cost*1.25
              WHERE group=10";
mysql_query(&amp;mysql,stmt);
printf("%ld products updated",
       (long) mysql_affected_rows(&amp;mysql));
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-autocommit"></a>27.8.7.2 mysql_autocommit()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710575449120"></a><p>
        <code class="literal">my_bool mysql_autocommit(MYSQL *mysql, my_bool
        mode)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-autocommit-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Sets autocommit mode on if <code class="literal">mode</code> is 1, off
          if <code class="literal">mode</code> is 0.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-autocommit-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-autocommit-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-change-user"></a>27.8.7.3 mysql_change_user()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710575439312"></a><p>
        <code class="literal">my_bool mysql_change_user(MYSQL *mysql, const char
        *user, const char *password, const char *db)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-change-user-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Changes the user and causes the database specified by
          <code class="literal">db</code> to become the default (current) database
          on the connection specified by <code class="literal">mysql</code>. In
          subsequent queries, this database is the default for table
          references that include no explicit database specifier.
        </p><p>
          <a class="link" href="connectors-apis.html#mysql-change-user" title="27.8.7.3 mysql_change_user()"><code class="literal">mysql_change_user()</code></a> fails if
          the connected user cannot be authenticated or does not have
          permission to use the database. In this case, the user and
          database are not changed.
        </p><p>
          Pass a <code class="literal">db</code> parameter of
          <code class="literal">NULL</code> if you do not want to have a default
          database.
        </p><p>
          This function resets the session state as if one had done a
          new connect and reauthenticated. (See
          <a class="xref" href="connectors-apis.html#c-api-auto-reconnect" title="27.8.20 C API Automatic Reconnection Control">Section 27.8.20, “C API Automatic Reconnection Control”</a>.) It always performs a
          <a class="link" href="sql-syntax.html#commit" title="13.3.1 START TRANSACTION, COMMIT, and ROLLBACK Syntax"><code class="literal">ROLLBACK</code></a> of
          any active transactions, closes and drops all temporary
          tables, and unlocks all locked tables. Session system
          variables are reset to the values of the corresponding global
          system variables. Prepared statements are released and
          <a class="link" href="sql-syntax.html#handler" title="13.2.4 HANDLER Syntax"><code class="literal">HANDLER</code></a> variables are closed.
          Locks acquired with <a class="link" href="functions.html#function_get-lock"><code class="literal">GET_LOCK()</code></a>
          are released. These effects occur even if the user did not
          change.
        </p><p>
          To reset the connection state in a more lightweight manner
          without changing the user, use
          <a class="link" href="connectors-apis.html#mysql-reset-connection" title="27.8.7.60 mysql_reset_connection()"><code class="literal">mysql_reset_connection()</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-change-user-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-change-user-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          The same that you can get from
          <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a>, plus:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_er_unknown_com_error"><code class="literal">ER_UNKNOWN_COM_ERROR</code></a>
            </p><p>
              The MySQL server does not implement this command (probably
              an old server).
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_er_access_denied_error"><code class="literal">ER_ACCESS_DENIED_ERROR</code></a>
            </p><p>
              The user or password was wrong.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_er_bad_db_error"><code class="literal">ER_BAD_DB_ERROR</code></a>
            </p><p>
              The database did not exist.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_er_dbaccess_denied_error"><code class="literal">ER_DBACCESS_DENIED_ERROR</code></a>
            </p><p>
              The user did not have access rights to the database.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_er_wrong_db_name"><code class="literal">ER_WRONG_DB_NAME</code></a>
            </p><p>
              The database name was too long.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-change-user-example"></a>Example</h5>

</div>

</div>

</div>
<pre data-lang="c" class="programlisting">
if (mysql_change_user(&amp;mysql, "user", "<em class="replaceable"><code>password</code></em>", "new_database"))
{
   fprintf(stderr, "Failed to change user.  Error: %s\n",
           mysql_error(&amp;mysql));
}
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-character-set-name"></a>27.8.7.4 mysql_character_set_name()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710575390240"></a><p>
        <code class="literal">const char *mysql_character_set_name(MYSQL
        *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-character-set-name-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns the default character set name for the current
          connection.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-character-set-name-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          The default character set name
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-character-set-name-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-close"></a>27.8.7.5 mysql_close()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710575381616"></a><p>
        <code class="literal">void mysql_close(MYSQL *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-close-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Closes a previously opened connection.
          <a class="link" href="connectors-apis.html#mysql-close" title="27.8.7.5 mysql_close()"><code class="literal">mysql_close()</code></a> also deallocates
          the connection handler pointed to by <code class="literal">mysql</code>
          if the handler was allocated automatically by
          <a class="link" href="connectors-apis.html#mysql-init" title="27.8.7.37 mysql_init()"><code class="literal">mysql_init()</code></a> or
          <a class="link" href="connectors-apis.html#mysql-connect" title="27.8.7.7 mysql_connect()"><code class="literal">mysql_connect()</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-close-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-close-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-commit"></a>27.8.7.6 mysql_commit()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710575368688"></a><p>
        <code class="literal">my_bool mysql_commit(MYSQL *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-commit-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Commits the current transaction.
        </p><p>
          The action of this function is subject to the value of the
          <a class="link" href="server-administration.html#sysvar_completion_type"><code class="literal">completion_type</code></a> system
          variable. In particular, if the value of
          <a class="link" href="server-administration.html#sysvar_completion_type"><code class="literal">completion_type</code></a> is
          <code class="literal">RELEASE</code> (or 2), the server performs a
          release after terminating a transaction and closes the client
          connection. Call <a class="link" href="connectors-apis.html#mysql-close" title="27.8.7.5 mysql_close()"><code class="literal">mysql_close()</code></a>
          from the client program to close the connection from the
          client side.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-commit-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-commit-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-connect"></a>27.8.7.7 mysql_connect()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710575354960"></a><p>
        <code class="literal">MYSQL *mysql_connect(MYSQL *mysql, const char *host,
        const char *user, const char *passwd)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-connect-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          This function is deprecated. Use
          <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a> instead.
        </p><p>
          <a class="link" href="connectors-apis.html#mysql-connect" title="27.8.7.7 mysql_connect()"><code class="literal">mysql_connect()</code></a> attempts to
          establish a connection to a MySQL database engine running on
          <code class="literal">host</code>.
          <a class="link" href="connectors-apis.html#mysql-connect" title="27.8.7.7 mysql_connect()"><code class="literal">mysql_connect()</code></a> must complete
          successfully before you can execute any of the other API
          functions, with the exception of
          <a class="link" href="connectors-apis.html#mysql-get-client-info" title="27.8.7.27 mysql_get_client_info()"><code class="literal">mysql_get_client_info()</code></a>.
        </p><p>
          The meanings of the parameters are the same as for the
          corresponding parameters for
          <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a> with the
          difference that the connection parameter may be
          <code class="literal">NULL</code>. In this case, the C API allocates
          memory for the connection structure automatically and frees it
          when you call <a class="link" href="connectors-apis.html#mysql-close" title="27.8.7.5 mysql_close()"><code class="literal">mysql_close()</code></a>.
          The disadvantage of this approach is that you cannot retrieve
          an error message if the connection fails. (To get error
          information from <a class="link" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()"><code class="literal">mysql_errno()</code></a>
          or <a class="link" href="connectors-apis.html#mysql-error" title="27.8.7.15 mysql_error()"><code class="literal">mysql_error()</code></a>, you must
          provide a valid <code class="literal">MYSQL</code> pointer.)
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-connect-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Same as for
          <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-connect-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          Same as for
          <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a>.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-create-db"></a>27.8.7.8 mysql_create_db()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710575329920"></a><p>
        <code class="literal">int mysql_create_db(MYSQL *mysql, const char
        *db)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-create-db-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Creates the database named by the <code class="literal">db</code>
          parameter.
        </p><p>
          This function is deprecated. Use
          <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a> to issue an SQL
          <a class="link" href="sql-syntax.html#create-database" title="13.1.11 CREATE DATABASE Syntax"><code class="literal">CREATE DATABASE</code></a> statement
          instead.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-create-db-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-create-db-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-create-db-example"></a>Example</h5>

</div>

</div>

</div>
<pre data-lang="c" class="programlisting">
if(mysql_create_db(&amp;mysql, "my_database"))
{
   fprintf(stderr, "Failed to create new database.  Error: %s\n",
           mysql_error(&amp;mysql));
}
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-data-seek"></a>27.8.7.9 mysql_data_seek()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710575304736"></a><p>
        <code class="literal">void mysql_data_seek(MYSQL_RES *result, my_ulonglong
        offset)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-data-seek-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Seeks to an arbitrary row in a query result set. The
          <code class="literal">offset</code> value is a row number. Specify a
          value in the range from <code class="literal">0</code> to
          <a class="link" href="connectors-apis.html#mysql-num-rows" title="27.8.7.49 mysql_num_rows()"><code class="literal">mysql_num_rows(result)-1</code></a>.
        </p><p>
          This function requires that the result set structure contains
          the entire result of the query, so
          <a class="link" href="connectors-apis.html#mysql-data-seek" title="27.8.7.9 mysql_data_seek()"><code class="literal">mysql_data_seek()</code></a> may be used
          only in conjunction with
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a>, not with
          <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-data-seek-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-data-seek-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-debug"></a>27.8.7.10 mysql_debug()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710575289216"></a><p>
        <code class="literal">void mysql_debug(const char *debug)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-debug-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Does a <code class="literal">DBUG_PUSH</code> with the given string.
          <a class="link" href="connectors-apis.html#mysql-debug" title="27.8.7.10 mysql_debug()"><code class="literal">mysql_debug()</code></a> uses the Fred
          Fish debug library. To use this function, you must compile the
          client library to support debugging. See
          <a class="xref" href="extending-mysql.html#dbug-package" title="28.5.3 The DBUG Package">Section 28.5.3, “The DBUG Package”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-debug-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-debug-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-debug-example"></a>Example</h5>

</div>

</div>

</div>
<p>
          The call shown here causes the client library to generate a
          trace file in <code class="filename">/tmp/client.trace</code> on the
          client machine:
        </p><pre data-lang="c" class="programlisting">
mysql_debug("d:t:O,/tmp/client.trace");
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-drop-db"></a>27.8.7.11 mysql_drop_db()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710575274544"></a><p>
        <code class="literal">int mysql_drop_db(MYSQL *mysql, const char
        *db)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-drop-db-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Drops the database named by the <code class="literal">db</code>
          parameter.
        </p><p>
          This function is deprecated. Use
          <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a> to issue an SQL
          <a class="link" href="sql-syntax.html#drop-database" title="13.1.22 DROP DATABASE Syntax"><code class="literal">DROP DATABASE</code></a> statement
          instead.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-drop-db-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-drop-db-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-drop-db-example"></a>Example</h5>

</div>

</div>

</div>
<pre data-lang="c" class="programlisting">
if(mysql_drop_db(&amp;mysql, "my_database"))
  fprintf(stderr, "Failed to drop the database: Error: %s\n",
          mysql_error(&amp;mysql));
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-dump-debug-info"></a>27.8.7.12 mysql_dump_debug_info()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710575249408"></a><p>
        <code class="literal">int mysql_dump_debug_info(MYSQL *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-dump-debug-info-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Instructs the server to write debugging information to the
          error log. The connected user must have the
          <a class="link" href="security.html#priv_super"><code class="literal">SUPER</code></a> privilege.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-dump-debug-info-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-dump-debug-info-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-eof"></a>27.8.7.13 mysql_eof()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710575229904"></a><p>
        <code class="literal">my_bool mysql_eof(MYSQL_RES *result)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-eof-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          This function is deprecated.
          <a class="link" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()"><code class="literal">mysql_errno()</code></a> or
          <a class="link" href="connectors-apis.html#mysql-error" title="27.8.7.15 mysql_error()"><code class="literal">mysql_error()</code></a> may be used
          instead.
        </p><p>
          <a class="link" href="connectors-apis.html#mysql-eof" title="27.8.7.13 mysql_eof()"><code class="literal">mysql_eof()</code></a> determines whether
          the last row of a result set has been read.
        </p><p>
          If you acquire a result set from a successful call to
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a>, the
          client receives the entire set in one operation. In this case,
          a <code class="literal">NULL</code> return from
          <a class="link" href="connectors-apis.html#mysql-fetch-row" title="27.8.7.21 mysql_fetch_row()"><code class="literal">mysql_fetch_row()</code></a> always means
          the end of the result set has been reached and it is
          unnecessary to call
          <a class="link" href="connectors-apis.html#mysql-eof" title="27.8.7.13 mysql_eof()"><code class="literal">mysql_eof()</code></a>. When used with
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a>,
          <a class="link" href="connectors-apis.html#mysql-eof" title="27.8.7.13 mysql_eof()"><code class="literal">mysql_eof()</code></a> always returns
          true.
        </p><p>
          On the other hand, if you use
          <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a> to initiate
          a result set retrieval, the rows of the set are obtained from
          the server one by one as you call
          <a class="link" href="connectors-apis.html#mysql-fetch-row" title="27.8.7.21 mysql_fetch_row()"><code class="literal">mysql_fetch_row()</code></a> repeatedly.
          Because an error may occur on the connection during this
          process, a <code class="literal">NULL</code> return value from
          <a class="link" href="connectors-apis.html#mysql-fetch-row" title="27.8.7.21 mysql_fetch_row()"><code class="literal">mysql_fetch_row()</code></a> does not
          necessarily mean the end of the result set was reached
          normally. In this case, you can use
          <a class="link" href="connectors-apis.html#mysql-eof" title="27.8.7.13 mysql_eof()"><code class="literal">mysql_eof()</code></a> to determine what
          happened. <a class="link" href="connectors-apis.html#mysql-eof" title="27.8.7.13 mysql_eof()"><code class="literal">mysql_eof()</code></a> returns
          a nonzero value if the end of the result set was reached and
          zero if an error occurred.
        </p><p>
          Historically, <a class="link" href="connectors-apis.html#mysql-eof" title="27.8.7.13 mysql_eof()"><code class="literal">mysql_eof()</code></a>
          predates the standard MySQL error functions
          <a class="link" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()"><code class="literal">mysql_errno()</code></a> and
          <a class="link" href="connectors-apis.html#mysql-error" title="27.8.7.15 mysql_error()"><code class="literal">mysql_error()</code></a>. Because those
          error functions provide the same information, their use is
          preferred over <a class="link" href="connectors-apis.html#mysql-eof" title="27.8.7.13 mysql_eof()"><code class="literal">mysql_eof()</code></a>,
          which is deprecated. (In fact, they provide more information,
          because <a class="link" href="connectors-apis.html#mysql-eof" title="27.8.7.13 mysql_eof()"><code class="literal">mysql_eof()</code></a> returns
          only a boolean value whereas the error functions indicate a
          reason for the error when one occurs.)
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-eof-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if the end of the result set has
          been reached.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-eof-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-eof-example"></a>Example</h5>

</div>

</div>

</div>
<p>
          The following example shows how you might use
          <a class="link" href="connectors-apis.html#mysql-eof" title="27.8.7.13 mysql_eof()"><code class="literal">mysql_eof()</code></a>:
        </p><pre data-lang="c" class="programlisting">
mysql_query(&amp;mysql,"SELECT * FROM some_table");
result = mysql_use_result(&amp;mysql);
while((row = mysql_fetch_row(result)))
{
    // do something with data
}
if(!mysql_eof(result))  // mysql_fetch_row() failed due to an error
{
    fprintf(stderr, "Error: %s\n", mysql_error(&amp;mysql));
}
</pre><p>
          However, you can achieve the same effect with the standard
          MySQL error functions:
        </p><pre data-lang="c" class="programlisting">
mysql_query(&amp;mysql,"SELECT * FROM some_table");
result = mysql_use_result(&amp;mysql);
while((row = mysql_fetch_row(result)))
{
    // do something with data
}
if(mysql_errno(&amp;mysql))  // mysql_fetch_row() failed due to an error
{
    fprintf(stderr, "Error: %s\n", mysql_error(&amp;mysql));
}
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-errno"></a>27.8.7.14 mysql_errno()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710575187584"></a><p>
        <code class="literal">unsigned int mysql_errno(MYSQL *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-errno-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          For the connection specified by <code class="literal">mysql</code>,
          <a class="link" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()"><code class="literal">mysql_errno()</code></a> returns the
          error code for the most recently invoked API function that can
          succeed or fail. A return value of zero means that no error
          occurred. Client error message numbers are listed in the MySQL
          <code class="filename">errmsg.h</code> header file. Server error
          message numbers are listed in
          <code class="filename">mysqld_error.h</code>. Errors also are listed at
          <a class="xref" href="error-handling.html" title="Appendix B Errors, Error Codes, and Common Problems">Appendix B, <i>Errors, Error Codes, and Common Problems</i></a>.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
            Some functions such as
            <a class="link" href="connectors-apis.html#mysql-fetch-row" title="27.8.7.21 mysql_fetch_row()"><code class="literal">mysql_fetch_row()</code></a> do not set
            <a class="link" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()"><code class="literal">mysql_errno()</code></a> if they
            succeed. A rule of thumb is that all functions that have to
            ask the server for information reset
            <a class="link" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()"><code class="literal">mysql_errno()</code></a> if they
            succeed.
</p>
</div>
<p>
          MySQL-specific error numbers returned by
          <a class="link" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()"><code class="literal">mysql_errno()</code></a> differ from
          SQLSTATE values returned by
          <a class="link" href="connectors-apis.html#mysql-sqlstate" title="27.8.7.72 mysql_sqlstate()"><code class="literal">mysql_sqlstate()</code></a>. For example,
          the <a class="link" href="programs.html#mysql" title="4.5.1 mysql — The MySQL Command-Line Tool"><span class="command"><strong>mysql</strong></span></a> client program displays errors
          using the following format, where <code class="literal">1146</code> is
          the <a class="link" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()"><code class="literal">mysql_errno()</code></a> value and
          <code class="literal">'42S02'</code> is the corresponding
          <a class="link" href="connectors-apis.html#mysql-sqlstate" title="27.8.7.72 mysql_sqlstate()"><code class="literal">mysql_sqlstate()</code></a> value:
        </p><pre data-lang="sql" class="programlisting">
shell&gt; <strong class="userinput"><code>SELECT * FROM no_such_table;</code></strong>
ERROR 1146 (42S02): Table 'test.no_such_table' doesn't exist
</pre>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-errno-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          An error code value for the last
          <code class="literal">mysql_<em class="replaceable"><code>xxx</code></em>()</code>
          call, if it failed. zero means no error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-errno-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-error"></a>27.8.7.15 mysql_error()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710575159040"></a><p>
        <code class="literal">const char *mysql_error(MYSQL *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-error-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          For the connection specified by <code class="literal">mysql</code>,
          <a class="link" href="connectors-apis.html#mysql-error" title="27.8.7.15 mysql_error()"><code class="literal">mysql_error()</code></a> returns a
          null-terminated string containing the error message for the
          most recently invoked API function that failed. If a function
          did not fail, the return value of
          <a class="link" href="connectors-apis.html#mysql-error" title="27.8.7.15 mysql_error()"><code class="literal">mysql_error()</code></a> may be the
          previous error or an empty string to indicate no error.
        </p><p>
          A rule of thumb is that all functions that have to ask the
          server for information reset
          <a class="link" href="connectors-apis.html#mysql-error" title="27.8.7.15 mysql_error()"><code class="literal">mysql_error()</code></a> if they succeed.
        </p><p>
          For functions that reset
          <a class="link" href="connectors-apis.html#mysql-error" title="27.8.7.15 mysql_error()"><code class="literal">mysql_error()</code></a>, either of these
          two tests can be used to check for an error:
        </p><pre data-lang="c" class="programlisting">
if(*mysql_error(&amp;mysql))
{
  // an error occurred
}

if(mysql_error(&amp;mysql)[0])
{
  // an error occurred
}
</pre><p>
          The language of the client error messages may be changed by
          recompiling the MySQL client library. You can choose error
          messages in several different languages. See
          <a class="xref" href="charset.html#error-message-language" title="10.11 Setting the Error Message Language">Section 10.11, “Setting the Error Message Language”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-error-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          A null-terminated character string that describes the error.
          An empty string if no error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-error-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>

<div class="section">

<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-escape-string"></a>27.8.7.16 mysql_escape_string()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710575141312"></a>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
          Do not use this function.
          <a class="link" href="connectors-apis.html#mysql-escape-string" title="27.8.7.16 mysql_escape_string()"><code class="literal">mysql_escape_string()</code></a> does not
          have arguments that enable it to respect the current character
          set or the quoting context. Use
          <a class="link" href="connectors-apis.html#mysql-real-escape-string-quote" title="27.8.7.56 mysql_real_escape_string_quote()"><code class="literal">mysql_real_escape_string_quote()</code></a>
          instead.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-fetch-field"></a>27.8.7.17 mysql_fetch_field()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710575135600"></a><p>
        <code class="literal">MYSQL_FIELD *mysql_fetch_field(MYSQL_RES
        *result)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-fetch-field-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns the definition of one column of a result set as a
          <code class="literal">MYSQL_FIELD</code> structure. Call this function
          repeatedly to retrieve information about all columns in the
          result set.
          <a class="link" href="connectors-apis.html#mysql-fetch-field" title="27.8.7.17 mysql_fetch_field()"><code class="literal">mysql_fetch_field()</code></a> returns
          <code class="literal">NULL</code> when no more fields are left.
        </p><p>
          <a class="link" href="connectors-apis.html#mysql-fetch-field" title="27.8.7.17 mysql_fetch_field()"><code class="literal">mysql_fetch_field()</code></a> is reset
          to return information about the first field each time you
          execute a new <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a> query. The
          field returned by
          <a class="link" href="connectors-apis.html#mysql-fetch-field" title="27.8.7.17 mysql_fetch_field()"><code class="literal">mysql_fetch_field()</code></a> is also
          affected by calls to
          <a class="link" href="connectors-apis.html#mysql-field-seek" title="27.8.7.23 mysql_field_seek()"><code class="literal">mysql_field_seek()</code></a>.
        </p><p>
          If you've called <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a>
          to perform a <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a> on a table
          but have not called
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a>, MySQL
          returns the default blob length (8KB) if you call
          <a class="link" href="connectors-apis.html#mysql-fetch-field" title="27.8.7.17 mysql_fetch_field()"><code class="literal">mysql_fetch_field()</code></a> to ask for
          the length of a <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">BLOB</code></a> field.
          (The 8KB size is chosen because MySQL does not know the
          maximum length for the <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">BLOB</code></a>.
          This should be made configurable sometime.) Once you've
          retrieved the result set,
          <code class="literal">field-&gt;max_length</code> contains the length of
          the largest value for this column in the specific query.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-fetch-field-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          The <code class="literal">MYSQL_FIELD</code> structure for the current
          column. <code class="literal">NULL</code> if no columns are left.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-fetch-field-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-fetch-field-example"></a>Example</h5>

</div>

</div>

</div>
<pre data-lang="c" class="programlisting">
MYSQL_FIELD *field;

while((field = mysql_fetch_field(result)))
{
    printf("field name %s\n", field-&gt;name);
}
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-fetch-field-direct"></a>27.8.7.18 mysql_fetch_field_direct()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710575105712"></a><p>
        <code class="literal">MYSQL_FIELD *mysql_fetch_field_direct(MYSQL_RES
        *result, unsigned int fieldnr)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-fetch-field-direct-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Given a field number <code class="literal">fieldnr</code> for a column
          within a result set, returns that column's field definition as
          a <code class="literal">MYSQL_FIELD</code> structure. Use this function
          to retrieve the definition for an arbitrary column. Specify a
          value for <code class="literal">fieldnr</code> in the range from 0 to
          <a class="link" href="connectors-apis.html#mysql-num-fields" title="27.8.7.48 mysql_num_fields()"><code class="literal">mysql_num_fields(result)-1</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-fetch-field-direct-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          The <code class="literal">MYSQL_FIELD</code> structure for the specified
          column.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-fetch-field-direct-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-fetch-field-direct-example"></a>Example</h5>

</div>

</div>

</div>
<pre data-lang="c" class="programlisting">
unsigned int num_fields;
unsigned int i;
MYSQL_FIELD *field;

num_fields = mysql_num_fields(result);
for(i = 0; i &lt; num_fields; i++)
{
    field = mysql_fetch_field_direct(result, i);
    printf("Field %u is %s\n", i, field-&gt;name);
}
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-fetch-fields"></a>27.8.7.19 mysql_fetch_fields()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710575090048"></a><p>
        <code class="literal">MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES
        *result)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-fetch-fields-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns an array of all <code class="literal">MYSQL_FIELD</code>
          structures for a result set. Each structure provides the field
          definition for one column of the result set.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-fetch-fields-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          An array of <code class="literal">MYSQL_FIELD</code> structures for all
          columns of a result set.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-fetch-fields-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-fetch-fields-example"></a>Example</h5>

</div>

</div>

</div>
<pre data-lang="c" class="programlisting">
unsigned int num_fields;
unsigned int i;
MYSQL_FIELD *fields;

num_fields = mysql_num_fields(result);
fields = mysql_fetch_fields(result);
for(i = 0; i &lt; num_fields; i++)
{
   printf("Field %u is %s\n", i, fields[i].name);
}
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-fetch-lengths"></a>27.8.7.20 mysql_fetch_lengths()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710575077520"></a><p>
        <code class="literal">unsigned long *mysql_fetch_lengths(MYSQL_RES
        *result)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-fetch-lengths-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns the lengths of the columns of the current row within a
          result set. If you plan to copy field values, this length
          information is also useful for optimization, because you can
          avoid calling <code class="literal">strlen()</code>. In addition, if the
          result set contains binary data, you
          <span class="bold"><strong>must</strong></span> use this function to
          determine the size of the data, because
          <code class="literal">strlen()</code> returns incorrect results for any
          field containing null characters.
        </p><p>
          The length for empty columns and for columns containing
          <code class="literal">NULL</code> values is zero. To see how to
          distinguish these two cases, see the description for
          <a class="link" href="connectors-apis.html#mysql-fetch-row" title="27.8.7.21 mysql_fetch_row()"><code class="literal">mysql_fetch_row()</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-fetch-lengths-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          An array of unsigned long integers representing the size of
          each column (not including any terminating null bytes).
          <code class="literal">NULL</code> if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-fetch-lengths-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          <a class="link" href="connectors-apis.html#mysql-fetch-lengths" title="27.8.7.20 mysql_fetch_lengths()"><code class="literal">mysql_fetch_lengths()</code></a> is valid
          only for the current row of the result set. It returns
          <code class="literal">NULL</code> if you call it before calling
          <a class="link" href="connectors-apis.html#mysql-fetch-row" title="27.8.7.21 mysql_fetch_row()"><code class="literal">mysql_fetch_row()</code></a> or after
          retrieving all rows in the result.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-fetch-lengths-example"></a>Example</h5>

</div>

</div>

</div>
<pre data-lang="c" class="programlisting">
MYSQL_ROW row;
unsigned long *lengths;
unsigned int num_fields;
unsigned int i;

row = mysql_fetch_row(result);
if (row)
{
    num_fields = mysql_num_fields(result);
    lengths = mysql_fetch_lengths(result);
    for(i = 0; i &lt; num_fields; i++)
    {
         printf("Column %u is %lu bytes in length.\n",
                i, lengths[i]);
    }
}
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-fetch-row"></a>27.8.7.21 mysql_fetch_row()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710575057088"></a><p>
        <code class="literal">MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-fetch-row-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Retrieves the next row of a result set. When used after
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a>,
          <a class="link" href="connectors-apis.html#mysql-fetch-row" title="27.8.7.21 mysql_fetch_row()"><code class="literal">mysql_fetch_row()</code></a> returns
          <code class="literal">NULL</code> when there are no more rows to
          retrieve. When used after
          <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a>,
          <a class="link" href="connectors-apis.html#mysql-fetch-row" title="27.8.7.21 mysql_fetch_row()"><code class="literal">mysql_fetch_row()</code></a> returns
          <code class="literal">NULL</code> when there are no more rows to
          retrieve or if an error occurred.
        </p><p>
          The number of values in the row is given by
          <a class="link" href="connectors-apis.html#mysql-num-fields" title="27.8.7.48 mysql_num_fields()"><code class="literal">mysql_num_fields(result)</code></a>. If
          <code class="literal">row</code> holds the return value from a call to
          <a class="link" href="connectors-apis.html#mysql-fetch-row" title="27.8.7.21 mysql_fetch_row()"><code class="literal">mysql_fetch_row()</code></a>, pointers to
          the values are accessed as <code class="literal">row[0]</code> to
          <code class="literal">row[mysql_num_fields(result)-1]</code>.
          <code class="literal">NULL</code> values in the row are indicated by
          <code class="literal">NULL</code> pointers.
        </p><p>
          The lengths of the field values in the row may be obtained by
          calling <a class="link" href="connectors-apis.html#mysql-fetch-lengths" title="27.8.7.20 mysql_fetch_lengths()"><code class="literal">mysql_fetch_lengths()</code></a>.
          Empty fields and fields containing <code class="literal">NULL</code>
          both have length 0; you can distinguish these by checking the
          pointer for the field value. If the pointer is
          <code class="literal">NULL</code>, the field is <code class="literal">NULL</code>;
          otherwise, the field is empty.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-fetch-row-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          A <code class="literal">MYSQL_ROW</code> structure for the next row.
          <code class="literal">NULL</code> if there are no more rows to retrieve
          or if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-fetch-row-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          Errors are not reset between calls to
          <a class="link" href="connectors-apis.html#mysql-fetch-row" title="27.8.7.21 mysql_fetch_row()"><code class="literal">mysql_fetch_row()</code></a>
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-fetch-row-example"></a>Example</h5>

</div>

</div>

</div>
<pre data-lang="c" class="programlisting">
MYSQL_ROW row;
unsigned int num_fields;
unsigned int i;

num_fields = mysql_num_fields(result);
while ((row = mysql_fetch_row(result)))
{
   unsigned long *lengths;
   lengths = mysql_fetch_lengths(result);
   for(i = 0; i &lt; num_fields; i++)
   {
       printf("[%.*s] ", (int) lengths[i],
              row[i] ? row[i] : "NULL");
   }
   printf("\n");
}
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-field-count"></a>27.8.7.22 mysql_field_count()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710575020848"></a><p>
        <code class="literal">unsigned int mysql_field_count(MYSQL *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-field-count-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns the number of columns for the most recent query on the
          connection.
        </p><p>
          The normal use of this function is when
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a> returned
          <code class="literal">NULL</code> (and thus you have no result set
          pointer). In this case, you can call
          <a class="link" href="connectors-apis.html#mysql-field-count" title="27.8.7.22 mysql_field_count()"><code class="literal">mysql_field_count()</code></a> to
          determine whether
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a> should
          have produced a nonempty result. This enables the client
          program to take proper action without knowing whether the
          query was a <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a> (or
          <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a>-like) statement. The
          example shown here illustrates how this may be done.
        </p><p>
          See <a class="xref" href="connectors-apis.html#null-mysql-store-result" title="27.8.21.1 Why mysql_store_result() Sometimes Returns NULL After mysql_query() Returns Success">Section 27.8.21.1, “Why mysql_store_result() Sometimes Returns NULL After mysql_query()
        Returns Success”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-field-count-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          An unsigned integer representing the number of columns in a
          result set.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-field-count-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-field-count-example"></a>Example</h5>

</div>

</div>

</div>
<pre data-lang="c" class="programlisting">
MYSQL_RES *result;
unsigned int num_fields;
unsigned int num_rows;

if (mysql_query(&amp;mysql,query_string))
{
    // error
}
else // query succeeded, process any data returned by it
{
    result = mysql_store_result(&amp;mysql);
    if (result)  // there are rows
    {
        num_fields = mysql_num_fields(result);
        // retrieve rows, then call mysql_free_result(result)
    }
    else  // mysql_store_result() returned nothing; should it have?
    {
        if(mysql_field_count(&amp;mysql) == 0)
        {
            // query does not return data
            // (it was not a SELECT)
            num_rows = mysql_affected_rows(&amp;mysql);
        }
        else // mysql_store_result() should have returned data
        {
            fprintf(stderr, "Error: %s\n", mysql_error(&amp;mysql));
        }
    }
}
</pre><p>
          An alternative is to replace the
          <a class="link" href="connectors-apis.html#mysql-field-count" title="27.8.7.22 mysql_field_count()"><code class="literal">mysql_field_count(&amp;mysql)</code></a>
          call with
          <a class="link" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()"><code class="literal">mysql_errno(&amp;mysql)</code></a>. In
          this case, you are checking directly for an error from
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a> rather
          than inferring from the value of
          <a class="link" href="connectors-apis.html#mysql-field-count" title="27.8.7.22 mysql_field_count()"><code class="literal">mysql_field_count()</code></a> whether
          the statement was a <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a>.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-field-seek"></a>27.8.7.23 mysql_field_seek()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574992848"></a><p>
        <code class="literal">MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result,
        MYSQL_FIELD_OFFSET offset)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-field-seek-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Sets the field cursor to the given offset. The next call to
          <a class="link" href="connectors-apis.html#mysql-fetch-field" title="27.8.7.17 mysql_fetch_field()"><code class="literal">mysql_fetch_field()</code></a> retrieves
          the field definition of the column associated with that
          offset.
        </p><p>
          To seek to the beginning of a row, pass an
          <code class="literal">offset</code> value of zero.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-field-seek-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          The previous value of the field cursor.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-field-seek-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-field-tell"></a>27.8.7.24 mysql_field_tell()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574981664"></a><p>
        <code class="literal">MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES
        *result)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-field-tell-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns the position of the field cursor used for the last
          <a class="link" href="connectors-apis.html#mysql-fetch-field" title="27.8.7.17 mysql_fetch_field()"><code class="literal">mysql_fetch_field()</code></a>. This
          value can be used as an argument to
          <a class="link" href="connectors-apis.html#mysql-field-seek" title="27.8.7.23 mysql_field_seek()"><code class="literal">mysql_field_seek()</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-field-tell-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          The current offset of the field cursor.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-field-tell-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-free-result"></a>27.8.7.25 mysql_free_result()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574970752"></a><p>
        <code class="literal">void mysql_free_result(MYSQL_RES *result)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-free-result-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Frees the memory allocated for a result set by
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a>,
          <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a>,
          <a class="link" href="connectors-apis.html#mysql-list-dbs" title="27.8.7.42 mysql_list_dbs()"><code class="literal">mysql_list_dbs()</code></a>, and so
          forth. When you are done with a result set, you must free the
          memory it uses by calling
          <a class="link" href="connectors-apis.html#mysql-free-result" title="27.8.7.25 mysql_free_result()"><code class="literal">mysql_free_result()</code></a>.
        </p><p>
          Do not attempt to access a result set after freeing it.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-free-result-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-free-result-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-get-character-set-info"></a>27.8.7.26 mysql_get_character_set_info()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574956576"></a><p>
        <code class="literal">void mysql_get_character_set_info(MYSQL *mysql,
        MY_CHARSET_INFO *cs)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-get-character-set-info-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          This function provides information about the default client
          character set. The default character set may be changed with
          the <a class="link" href="connectors-apis.html#mysql-set-character-set" title="27.8.7.67 mysql_set_character_set()"><code class="literal">mysql_set_character_set()</code></a>
          function.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-get-character-set-info-example"></a>Example</h5>

</div>

</div>

</div>
<p>
          This example shows the fields that are available in the
          <code class="literal">MY_CHARSET_INFO</code> structure:
        </p><pre data-lang="c" class="programlisting">
if (!mysql_set_character_set(&amp;mysql, "utf8"))
{
    MY_CHARSET_INFO cs;
    mysql_get_character_set_info(&amp;mysql, &amp;cs);
    printf("character set information:\n");
    printf("character set+collation number: %d\n", cs.number);
    printf("character set name: %s\n", cs.name);
    printf("collation name: %s\n", cs.csname);
    printf("comment: %s\n", cs.comment);
    printf("directory: %s\n", cs.dir);
    printf("multi byte character min. length: %d\n", cs.mbminlen);
    printf("multi byte character max. length: %d\n", cs.mbmaxlen);
}
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-get-client-info"></a>27.8.7.27 mysql_get_client_info()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574945136"></a><p>
        <code class="literal">const char *mysql_get_client_info(void)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-get-client-info-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns a string that represents the MySQL client library
          version; for example, <code class="literal">"5.7.23"</code>.
        </p><p>
          The function value is the version of MySQL or Connector/C that
          provides the client library. For more information, see
          <a class="xref" href="connectors-apis.html#c-api-server-client-versions" title="27.8.4.5 C API Server and Client Library Versions">Section 27.8.4.5, “C API Server and Client Library Versions”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-get-client-info-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          A character string that represents the MySQL client library
          version.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-get-client-info-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-get-client-version"></a>27.8.7.28 mysql_get_client_version()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574934576"></a><p>
        <code class="literal">unsigned long mysql_get_client_version(void)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-get-client-version-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns an integer that represents the MySQL client library
          version. The value has the format <code class="literal">XYYZZ</code>
          where <code class="literal">X</code> is the major version,
          <code class="literal">YY</code> is the release level (or minor version),
          and <code class="literal">ZZ</code> is the sub-version within the
          release level:
        </p><pre data-lang="simple" class="programlisting">
major_version*10000 + release_level*100 + sub_version
</pre><p>
          For example, <code class="literal">"5.7.23"</code> is
          returned as <code class="literal">50723</code>.
        </p><p>
          The function value is the version of MySQL or Connector/C that
          provides the client library. For more information, see
          <a class="xref" href="connectors-apis.html#c-api-server-client-versions" title="27.8.4.5 C API Server and Client Library Versions">Section 27.8.4.5, “C API Server and Client Library Versions”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-get-client-version-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          An integer that represents the MySQL client library version.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-get-client-version-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-get-host-info"></a>27.8.7.29 mysql_get_host_info()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574918928"></a><p>
        <code class="literal">const char *mysql_get_host_info(MYSQL *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-get-host-info-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns a string describing the type of connection in use,
          including the server host name.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-get-host-info-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          A character string representing the server host name and the
          connection type.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-get-host-info-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-get-option"></a>27.8.7.30 mysql_get_option()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574910352"></a><p>
        <code class="literal">int mysql_get_option(MYSQL *mysql, enum mysql_option
        option, const void *arg)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-get-option-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns the current value of an option settable using
          <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a>. The value
          should be treated as read only.
        </p><p>
          The <code class="literal">option</code> argument is the option for which
          you want its value. The <code class="literal">arg</code> argument is a
          pointer to a variable in which to store the option value.
          <code class="literal">arg</code> must be a pointer to a variable of the
          type appropriate for the <code class="literal">option</code> argument.
          The following table shows which variable type to use for each
          <code class="literal">option</code> value.
</p>
<div class="informaltable">
<table summary="Options for mysql_get_option()."><col width="20%"><col width="80%"><thead><tr>
              <th scope="col"><code class="literal">arg</code> Type</th>
              <th scope="col">Applicable <code class="literal">option</code> Values</th>
            </tr></thead><tbody><tr>
              <td scope="row"><code class="literal">unsigned int</code></td>
              <td><code class="literal">MYSQL_OPT_CONNECT_TIMEOUT</code>,
                <code class="literal">MYSQL_OPT_PROTOCOL</code>,
                <code class="literal">MYSQL_OPT_READ_TIMEOUT</code>,
                <code class="literal">MYSQL_OPT_RETRY_COUNT</code>,
                <code class="literal">MYSQL_OPT_SSL_MODE</code>,
                <code class="literal">MYSQL_OPT_WRITE_TIMEOUT</code></td>
            </tr><tr>
              <td scope="row"><code class="literal">unsigned long</code></td>
              <td><code class="literal">MYSQL_OPT_MAX_ALLOWED_PACKET</code>,
                <code class="literal">MYSQL_OPT_NET_BUFFER_LENGTH</code></td>
            </tr><tr>
              <td scope="row"><code class="literal">my_bool</code></td>
              <td><code class="literal">MYSQL_ENABLE_CLEARTEXT_PLUGIN</code>,
                <code class="literal">MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS</code>,
                <code class="literal">MYSQL_OPT_GUESS_CONNECTION</code>,
                <code class="literal">MYSQL_OPT_LOCAL_INFILE</code>,
                <code class="literal">MYSQL_OPT_RECONNECT</code>,
                <code class="literal">MYSQL_OPT_SSL_ENFORCE</code>,
                <code class="literal">MYSQL_OPT_SSL_VERIFY_SERVER_CERT</code>,
                <code class="literal">MYSQL_OPT_USE_EMBEDDED_CONNECTION</code>,
                <code class="literal">MYSQL_OPT_USE_REMOTE_CONNECTION</code>,
                <code class="literal">MYSQL_REPORT_DATA_TRUNCATION</code>,
                <code class="literal">MYSQL_SECURE_AUTH</code></td>
            </tr><tr>
              <td scope="row"><code class="literal">const char *</code></td>
              <td><code class="literal">MYSQL_DEFAULT_AUTH</code>,
                <code class="literal">MYSQL_OPT_BIND</code>,
                <code class="literal">MYSQL_OPT_SSL_CA</code>,
                <code class="literal">MYSQL_OPT_SSL_CAPATH</code>,
                <code class="literal">MYSQL_OPT_SSL_CERT</code>,
                <code class="literal">MYSQL_OPT_SSL_CIPHER</code>,
                <code class="literal">MYSQL_OPT_SSL_CRL</code>,
                <code class="literal">MYSQL_OPT_SSL_CRLPATH</code>,
                <code class="literal">MYSQL_OPT_SSL_KEY</code>,
                <code class="literal">MYSQL_OPT_TLS_VERSION</code>,
                <code class="literal">MYSQL_PLUGIN_DIR</code>,
                <code class="literal">MYSQL_READ_DEFAULT_FILE</code>,
                <code class="literal">MYSQL_READ_DEFAULT_GROUP</code>,
                <code class="literal">MYSQL_SERVER_PUBLIC_KEY</code>,
                <code class="literal">MYSQL_SET_CHARSET_DIR</code>,
                <code class="literal">MYSQL_SET_CHARSET_NAME</code>,
                <code class="literal">MYSQL_SET_CLIENT_IP</code>,
                <code class="literal">MYSQL_SHARED_MEMORY_BASE_NAME</code></td>
            </tr><tr>
              <td scope="row">argument not used</td>
              <td><code class="literal">MYSQL_OPT_COMPRESS</code></td>
            </tr><tr>
              <td scope="row">cannot be queried (error is returned)</td>
              <td><code class="literal">MYSQL_INIT_COMMAND</code>,
                <code class="literal">MYSQL_OPT_CONNECT_ATTR_DELETE</code>,
                <code class="literal">MYSQL_OPT_CONNECT_ATTR_RESET</code>,
                <code class="literal">MYSQL_OPT_NAMED_PIPE</code></td>
</tr></tbody></table>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-get-option-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred; this occurs
          for <code class="literal">option</code> values that cannot be queried.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-get-option-example"></a>Example</h5>

</div>

</div>

</div>
<p>
          The following call tests the
          <code class="literal">MYSQL_OPT_RECONNECT</code> option. After the call
          returns successfully, the value of
          <code class="literal">reconnect</code> is true or false to indicate
          whether automatic reconnection is enabled.
        </p><pre data-lang="c" class="programlisting">
my_bool reconnect;

if (mysql_get_option(mysql, MYSQL_OPT_RECONNECT, &amp;reconnect))
  fprintf(stderr, "mysql_get_options() failed\n");
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-get-proto-info"></a>27.8.7.31 mysql_get_proto_info()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574841280"></a><p>
        <code class="literal">unsigned int mysql_get_proto_info(MYSQL
        *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-get-proto-info-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns the protocol version used by current connection.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-get-proto-info-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          An unsigned integer representing the protocol version used by
          the current connection.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-get-proto-info-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-get-server-info"></a>27.8.7.32 mysql_get_server_info()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574832688"></a><p>
        <code class="literal">const char *mysql_get_server_info(MYSQL
        *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-get-server-info-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns a string that represents the MySQL server version; for
          example, <code class="literal">"5.7.23"</code>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-get-server-info-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          A character string that represents the MySQL server version.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-get-server-info-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-get-server-version"></a>27.8.7.33 mysql_get_server_version()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574823296"></a><p>
        <code class="literal">unsigned long mysql_get_server_version(MYSQL
        *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-get-server-version-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns an integer that represents the MySQL server version.
          The value has the format <code class="literal">XYYZZ</code> where
          <code class="literal">X</code> is the major version,
          <code class="literal">YY</code> is the release level (or minor version),
          and <code class="literal">ZZ</code> is the sub-version within the
          release level:
        </p><pre data-lang="simple" class="programlisting">
major_version*10000 + release_level*100 + sub_version
</pre><p>
          For example, <code class="literal">"5.7.23"</code> is
          returned as <code class="literal">50723</code>.
        </p><p>
          This function is useful in client programs for determining
          whether some version-specific server capability exists.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-get-server-version-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          An integer that represents the MySQL server version.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-get-server-version-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-get-ssl-cipher"></a>27.8.7.34 mysql_get_ssl_cipher()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574808368"></a><p>
        <code class="literal">const char *mysql_get_ssl_cipher(MYSQL
        *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-get-ssl-cipher-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          <a class="link" href="connectors-apis.html#mysql-get-ssl-cipher" title="27.8.7.34 mysql_get_ssl_cipher()"><code class="literal">mysql_get_ssl_cipher()</code></a> returns
          the encryption cipher used for the given connection to the
          server. <code class="literal">mysql</code> is the connection handler
          returned from <a class="link" href="connectors-apis.html#mysql-init" title="27.8.7.37 mysql_init()"><code class="literal">mysql_init()</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-get-ssl-cipher-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          A string naming the encryption cipher used for the connection,
          or <code class="literal">NULL</code> if the connection is not encrypted.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-hex-string"></a>27.8.7.35 mysql_hex_string()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574797568"></a><p>
        <code class="literal">unsigned long mysql_hex_string(char *to, const char
        *from, unsigned long length)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-hex-string-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          This function creates a legal SQL string for use in an SQL
          statement. See <a class="xref" href="language-structure.html#string-literals" title="9.1.1 String Literals">Section 9.1.1, “String Literals”</a>.
        </p><p>
          The string in the <code class="literal">from</code> argument is encoded
          in hexadecimal format, with each character encoded as two
          hexadecimal digits. The result is placed in the
          <code class="literal">to</code> argument, followed by a terminating null
          byte.
        </p><p>
          The string pointed to by <code class="literal">from</code> must be
          <code class="literal">length</code> bytes long. You must allocate the
          <code class="literal">to</code> buffer to be at least
          <code class="literal">length*2+1</code> bytes long. When
          <a class="link" href="connectors-apis.html#mysql-hex-string" title="27.8.7.35 mysql_hex_string()"><code class="literal">mysql_hex_string()</code></a> returns,
          the contents of <code class="literal">to</code> is a null-terminated
          string. The return value is the length of the encoded string,
          not including the terminating null byte.
        </p><p>
          The return value can be placed into an SQL statement using
          either <code class="literal">X'<em class="replaceable"><code>value</code></em>'</code>
          or <code class="literal">0x<em class="replaceable"><code>value</code></em></code>
          format. However, the return value does not include the
          <code class="literal">X'...'</code> or <code class="literal">0x</code>. The caller
          must supply whichever of those is desired.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-hex-string-example"></a>Example</h5>

</div>

</div>

</div>
<pre data-lang="c" class="programlisting">
char query[1000],*end;

end = strmov(query,"INSERT INTO test_table values(");
end = strmov(end,"X'");
end += mysql_hex_string(end,"What is this",12);
end = strmov(end,"',X'");
end += mysql_hex_string(end,"binary data: \0\r\n",16);
end = strmov(end,"')");

if (mysql_real_query(&amp;mysql,query,(unsigned int) (end - query)))
{
   fprintf(stderr, "Failed to insert row, Error: %s\n",
           mysql_error(&amp;mysql));
}
</pre><p>
          The <code class="literal">strmov()</code> function used in the example
          is included in the <code class="literal">libmysqlclient</code> library
          and works like <code class="literal">strcpy()</code> but returns a
          pointer to the terminating null of the first parameter.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-hex-string-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          The length of the encoded string that is placed into
          <code class="literal">to</code>, not including the terminating null
          character.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-hex-string-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-info"></a>27.8.7.36 mysql_info()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574770640"></a><p>
        <code class="literal">const char *mysql_info(MYSQL *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-info-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Retrieves a string providing information about the most
          recently executed statement, but only for the statements
          listed here. For other statements,
          <a class="link" href="connectors-apis.html#mysql-info" title="27.8.7.36 mysql_info()"><code class="literal">mysql_info()</code></a> returns
          <code class="literal">NULL</code>. The format of the string varies
          depending on the type of statement, as described here. The
          numbers are illustrative only; the string contains values
          appropriate for the statement.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="sql-syntax.html#insert-select" title="13.2.5.1 INSERT ... SELECT Syntax"><code class="literal">INSERT INTO
              ... SELECT ...</code></a>
            </p><p>
              String format: <code class="literal">Records: 100 Duplicates: 0
              Warnings: 0</code>
            </p></li><li class="listitem"><p>
              <code class="literal">INSERT INTO ... VALUES
              (...),(...),(...)...</code>
            </p><p>
              String format: <code class="literal">Records: 3 Duplicates: 0 Warnings:
              0</code>
            </p></li><li class="listitem"><p>
              <a class="link" href="sql-syntax.html#load-data" title="13.2.6 LOAD DATA INFILE Syntax"><code class="literal">LOAD DATA
              INFILE ...</code></a>
            </p><p>
              String format: <code class="literal">Records: 1 Deleted: 0 Skipped: 0
              Warnings: 0</code>
            </p></li><li class="listitem"><p>
              <a class="link" href="sql-syntax.html#alter-table" title="13.1.8 ALTER TABLE Syntax"><code class="literal">ALTER TABLE</code></a>
            </p><p>
              String format: <code class="literal">Records: 3 Duplicates: 0 Warnings:
              0</code>
            </p></li><li class="listitem"><p>
              <a class="link" href="sql-syntax.html#update" title="13.2.11 UPDATE Syntax"><code class="literal">UPDATE</code></a>
            </p><p>
              String format: <code class="literal">Rows matched: 40 Changed: 40
              Warnings: 0</code>
</p></li></ul>
</div>
<p>
          <a class="link" href="connectors-apis.html#mysql-info" title="27.8.7.36 mysql_info()"><code class="literal">mysql_info()</code></a> returns a
          non-<code class="literal">NULL</code> value for
          <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT ...
          VALUES</code></a> only for the multiple-row form of the
          statement (that is, only if multiple value lists are
          specified).
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-info-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          A character string representing additional information about
          the most recently executed statement. <code class="literal">NULL</code>
          if no information is available for the statement.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-info-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-init"></a>27.8.7.37 mysql_init()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574739776"></a><p>
        <code class="literal">MYSQL *mysql_init(MYSQL *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-init-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Allocates or initializes a <code class="literal">MYSQL</code> object
          suitable for
          <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a>. If
          <code class="literal">mysql</code> is a <code class="literal">NULL</code> pointer,
          the function allocates, initializes, and returns a new object.
          Otherwise, the object is initialized and the address of the
          object is returned. If
          <a class="link" href="connectors-apis.html#mysql-init" title="27.8.7.37 mysql_init()"><code class="literal">mysql_init()</code></a> allocates a new
          object, it is freed when
          <a class="link" href="connectors-apis.html#mysql-close" title="27.8.7.5 mysql_close()"><code class="literal">mysql_close()</code></a> is called to
          close the connection.
        </p><p>
          In a nonmulti-threaded environment,
          <a class="link" href="connectors-apis.html#mysql-init" title="27.8.7.37 mysql_init()"><code class="literal">mysql_init()</code></a> invokes
          <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a>
          automatically as necessary. However,
          <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a> is not
          thread-safe in a multi-threaded environment, and thus neither
          is <a class="link" href="connectors-apis.html#mysql-init" title="27.8.7.37 mysql_init()"><code class="literal">mysql_init()</code></a>. Before
          calling <a class="link" href="connectors-apis.html#mysql-init" title="27.8.7.37 mysql_init()"><code class="literal">mysql_init()</code></a>, either
          call <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a>
          prior to spawning any threads, or use a mutex to protect the
          <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a> call.
          This should be done prior to any other client library call.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-init-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          An initialized <code class="literal">MYSQL*</code> handler.
          <code class="literal">NULL</code> if there was insufficient memory to
          allocate a new object.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-init-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          In case of insufficient memory, <code class="literal">NULL</code> is
          returned.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-insert-id"></a>27.8.7.38 mysql_insert_id()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574713568"></a><p>
        <code class="literal">my_ulonglong mysql_insert_id(MYSQL *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-insert-id-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns the value generated for an
          <code class="literal">AUTO_INCREMENT</code> column by the previous
          <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT</code></a> or
          <a class="link" href="sql-syntax.html#update" title="13.2.11 UPDATE Syntax"><code class="literal">UPDATE</code></a> statement. Use this
          function after you have performed an
          <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT</code></a> statement into a table
          that contains an <code class="literal">AUTO_INCREMENT</code> field, or
          have used <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT</code></a> or
          <a class="link" href="sql-syntax.html#update" title="13.2.11 UPDATE Syntax"><code class="literal">UPDATE</code></a> to set a column value
          with
          <a class="link" href="functions.html#function_last-insert-id"><code class="literal">LAST_INSERT_ID(<em class="replaceable"><code>expr</code></em>)</code></a>.
        </p><p>
          The return value of
          <a class="link" href="connectors-apis.html#mysql-insert-id" title="27.8.7.38 mysql_insert_id()"><code class="literal">mysql_insert_id()</code></a> is always
          zero unless explicitly updated under one of the following
          conditions:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT</code></a> statements that
              store a value into an <code class="literal">AUTO_INCREMENT</code>
              column. This is true whether the value is automatically
              generated by storing the special values
              <code class="literal">NULL</code> or <code class="literal">0</code> into the
              column, or is an explicit nonspecial value.
            </p></li><li class="listitem"><p>
              In the case of a multiple-row
              <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT</code></a> statement,
              <a class="link" href="connectors-apis.html#mysql-insert-id" title="27.8.7.38 mysql_insert_id()"><code class="literal">mysql_insert_id()</code></a> returns
              the first automatically generated
              <code class="literal">AUTO_INCREMENT</code> value that was
              successfully inserted.
            </p><p>
              If no rows are successfully inserted,
              <a class="link" href="connectors-apis.html#mysql-insert-id" title="27.8.7.38 mysql_insert_id()"><code class="literal">mysql_insert_id()</code></a> returns
              0.
            </p></li><li class="listitem"><p>
              If an
              <a class="link" href="sql-syntax.html#insert-select" title="13.2.5.1 INSERT ... SELECT Syntax"><code class="literal">INSERT ...
              SELECT</code></a> statement is executed, and no
              automatically generated value is successfully inserted,
              <a class="link" href="connectors-apis.html#mysql-insert-id" title="27.8.7.38 mysql_insert_id()"><code class="literal">mysql_insert_id()</code></a> returns
              the ID of the last inserted row.
            </p></li><li class="listitem"><p>
              If an
              <a class="link" href="sql-syntax.html#insert-select" title="13.2.5.1 INSERT ... SELECT Syntax"><code class="literal">INSERT ...
              SELECT</code></a> statement uses
              <a class="link" href="functions.html#function_last-insert-id"><code class="literal">LAST_INSERT_ID(<em class="replaceable"><code>expr</code></em>)</code></a>,
              <a class="link" href="connectors-apis.html#mysql-insert-id" title="27.8.7.38 mysql_insert_id()"><code class="literal">mysql_insert_id()</code></a> returns
              <em class="replaceable"><code>expr</code></em>.
            </p></li><li class="listitem"><p>
              <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT</code></a> statements that
              generate an <code class="literal">AUTO_INCREMENT</code> value by
              inserting
              <a class="link" href="functions.html#function_last-insert-id"><code class="literal">LAST_INSERT_ID(<em class="replaceable"><code>expr</code></em>)</code></a>
              into any column or by updating any column to
              <a class="link" href="functions.html#function_last-insert-id"><code class="literal">LAST_INSERT_ID(<em class="replaceable"><code>expr</code></em>)</code></a>.
            </p></li><li class="listitem"><p>
              If the previous statement returned an error, the value of
              <a class="link" href="connectors-apis.html#mysql-insert-id" title="27.8.7.38 mysql_insert_id()"><code class="literal">mysql_insert_id()</code></a> is
              undefined.
</p></li></ul>
</div>
<p>
          The return value of
          <a class="link" href="connectors-apis.html#mysql-insert-id" title="27.8.7.38 mysql_insert_id()"><code class="literal">mysql_insert_id()</code></a> can be
          simplified to the following sequence:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
              If there is an <code class="literal">AUTO_INCREMENT</code> column,
              and an automatically generated value was successfully
              inserted, return the first such value.
            </p></li><li class="listitem"><p>
              If
              <a class="link" href="functions.html#function_last-insert-id"><code class="literal">LAST_INSERT_ID(<em class="replaceable"><code>expr</code></em>)</code></a>
              occurred in the statement, return
              <em class="replaceable"><code>expr</code></em>, even if there was an
              <code class="literal">AUTO_INCREMENT</code> column in the affected
              table.
            </p></li><li class="listitem"><p>
              The return value varies depending on the statement used.
              When called after an <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT</code></a>
              statement:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
                  If there is an <code class="literal">AUTO_INCREMENT</code>
                  column in the table, and there were some explicit
                  values for this column that were successfully inserted
                  into the table, return the last of the explicit
                  values.
</p></li></ul>
</div>
<p>
              When called after an
              <a class="link" href="sql-syntax.html#insert-on-duplicate" title="13.2.5.2 INSERT ... ON DUPLICATE KEY UPDATE Syntax"><code class="literal">INSERT
              ... ON DUPLICATE KEY UPDATE</code></a> statement:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
                  If there is an <code class="literal">AUTO_INCREMENT</code>
                  column in the table and there were some explicit
                  successfully inserted values or some updated values,
                  return the last of the inserted or updated values.
</p></li></ul>
</div>
</li></ol>
</div>
<p>
          <a class="link" href="connectors-apis.html#mysql-insert-id" title="27.8.7.38 mysql_insert_id()"><code class="literal">mysql_insert_id()</code></a> returns
          <code class="literal">0</code> if the previous statement does not use an
          <code class="literal">AUTO_INCREMENT</code> value. If you need to save
          the value for later, be sure to call
          <a class="link" href="connectors-apis.html#mysql-insert-id" title="27.8.7.38 mysql_insert_id()"><code class="literal">mysql_insert_id()</code></a> immediately
          after the statement that generates the value.
        </p><p>
          The value of <a class="link" href="connectors-apis.html#mysql-insert-id" title="27.8.7.38 mysql_insert_id()"><code class="literal">mysql_insert_id()</code></a>
          is affected only by statements issued within the current
          client connection. It is not affected by statements issued by
          other clients.
        </p><p>
          The <a class="link" href="functions.html#function_last-insert-id"><code class="literal">LAST_INSERT_ID()</code></a> SQL
          function will contain the value of the first automatically
          generated value that was successfully inserted.
          <a class="link" href="functions.html#function_last-insert-id"><code class="literal">LAST_INSERT_ID()</code></a> is not reset
          between statements because the value of that function is
          maintained in the server. Another difference from
          <a class="link" href="connectors-apis.html#mysql-insert-id" title="27.8.7.38 mysql_insert_id()"><code class="literal">mysql_insert_id()</code></a> is that
          <a class="link" href="functions.html#function_last-insert-id"><code class="literal">LAST_INSERT_ID()</code></a> is not updated
          if you set an <code class="literal">AUTO_INCREMENT</code> column to a
          specific nonspecial value. See
          <a class="xref" href="functions.html#information-functions" title="12.14 Information Functions">Section 12.14, “Information Functions”</a>.
        </p><p>
          <a class="link" href="connectors-apis.html#mysql-insert-id" title="27.8.7.38 mysql_insert_id()"><code class="literal">mysql_insert_id()</code></a> returns
          <code class="literal">0</code> following a
          <a class="link" href="sql-syntax.html#call" title="13.2.1 CALL Syntax"><code class="literal">CALL</code></a> statement for a stored
          procedure that generates an <code class="literal">AUTO_INCREMENT</code>
          value because in this case
          <a class="link" href="connectors-apis.html#mysql-insert-id" title="27.8.7.38 mysql_insert_id()"><code class="literal">mysql_insert_id()</code></a> applies to
          <a class="link" href="sql-syntax.html#call" title="13.2.1 CALL Syntax"><code class="literal">CALL</code></a> and not the statement
          within the procedure. Within the procedure, you can use
          <a class="link" href="functions.html#function_last-insert-id"><code class="literal">LAST_INSERT_ID()</code></a> at the SQL
          level to obtain the <code class="literal">AUTO_INCREMENT</code> value.
        </p><p>
          The reason for the differences between
          <a class="link" href="functions.html#function_last-insert-id"><code class="literal">LAST_INSERT_ID()</code></a> and
          <a class="link" href="connectors-apis.html#mysql-insert-id" title="27.8.7.38 mysql_insert_id()"><code class="literal">mysql_insert_id()</code></a> is that
          <a class="link" href="functions.html#function_last-insert-id"><code class="literal">LAST_INSERT_ID()</code></a> is made easy
          to use in scripts while
          <a class="link" href="connectors-apis.html#mysql-insert-id" title="27.8.7.38 mysql_insert_id()"><code class="literal">mysql_insert_id()</code></a> tries to
          provide more exact information about what happens to the
          <code class="literal">AUTO_INCREMENT</code> column.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
            The OK packet used in the client/server protocol holds
            information such as is used for session state tracking. When
            clients read the OK packet to know whether there is a
            session state change, this resets values such as the last
            insert ID and the number of affected rows. Such changes
            cause <a class="link" href="connectors-apis.html#mysql-insert-id" title="27.8.7.38 mysql_insert_id()"><code class="literal">mysql_insert_id()</code></a> to
            return 0 after execution of commands including but not
            necessarily limited to <code class="literal">COM_PING</code>,
            <code class="literal">COM_REFRESH</code>, and
            <code class="literal">COM_INIT_DB</code>.
</p>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-insert-id-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Described in the preceding discussion.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-insert-id-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_er_auto_increment_conflict"><code class="literal">ER_AUTO_INCREMENT_CONFLICT</code></a>
            </p><p>
              A user-specified <code class="literal">AUTO_INCREMENT</code> value
              in a multi <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT</code></a> statement
              falls within the range between the current
              <code class="literal">AUTO_INCREMENT</code> value and the sum of the
              current and number of rows affected values.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-kill"></a>27.8.7.39 mysql_kill()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574611584"></a><p>
        <code class="literal">int mysql_kill(MYSQL *mysql, unsigned long
        pid)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-kill-description"></a>Description</h5>

</div>

</div>

</div>

<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
            As of MySQL 5.7.11, <code class="literal">mysql_kill()</code> is
            deprecated and will be removed in a future version of MySQL.
            Instead, use <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a>
            to execute a <a class="link" href="sql-syntax.html#kill" title="13.7.6.4 KILL Syntax"><code class="literal">KILL</code></a> statement.
</p>
</div>
<p>
          Asks the server to kill the thread specified by
          <code class="literal">pid</code>.
        </p><p>
          This function is deprecated. Use
          <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a> to issue an SQL
          <a class="link" href="sql-syntax.html#kill" title="13.7.6.4 KILL Syntax"><code class="literal">KILL</code></a> statement instead.
        </p><p>
          <a class="link" href="connectors-apis.html#mysql-kill" title="27.8.7.39 mysql_kill()"><code class="literal">mysql_kill()</code></a> cannot handle
          values larger than 32 bits, but to guard against killing the
          wrong thread returns an error in these cases:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              If given an ID larger than 32 bits,
              <a class="link" href="connectors-apis.html#mysql-kill" title="27.8.7.39 mysql_kill()"><code class="literal">mysql_kill()</code></a> returns a
              <a class="link" href="error-handling.html#error_cr_invalid_conn_handle"><code class="literal">CR_INVALID_CONN_HANDLE</code></a>
              error.
            </p></li><li class="listitem"><p>
              After the server's internal thread ID counter reaches a
              value larger than 32 bits, it returns an
              <a class="link" href="error-handling.html#error_er_data_out_of_range"><code class="literal">ER_DATA_OUT_OF_RANGE</code></a> error
              for any <a class="link" href="connectors-apis.html#mysql-kill" title="27.8.7.39 mysql_kill()"><code class="literal">mysql_kill()</code></a>
              invocation and
              <a class="link" href="connectors-apis.html#mysql-kill" title="27.8.7.39 mysql_kill()"><code class="literal">mysql_kill()</code></a> fails.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-kill-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-kill-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_invalid_conn_handle"><code class="literal">CR_INVALID_CONN_HANDLE</code></a>
            </p><p>
              The <code class="literal">pid</code> was larger than 32 bits.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_er_data_out_of_range"><code class="literal">ER_DATA_OUT_OF_RANGE</code></a>
            </p><p>
              The server's internal thread ID counter has reached a
              value larger than 32 bits, at which point it rejects all
              <a class="link" href="connectors-apis.html#mysql-kill" title="27.8.7.39 mysql_kill()"><code class="literal">mysql_kill()</code></a> invocations.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-library-end"></a>27.8.7.40 mysql_library_end()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574568032"></a><p>
        <code class="literal">void mysql_library_end(void)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-library-end-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          This function finalizes the MySQL library. Call it when you
          are done using the library (for example, after disconnecting
          from the server). The action taken by the call depends on
          whether your application is linked to the MySQL client library
          or the MySQL embedded server library. For a client program
          linked against the <code class="literal">libmysqlclient</code> library
          by using the <code class="option">-lmysqlclient</code> flag,
          <a class="link" href="connectors-apis.html#mysql-library-end" title="27.8.7.40 mysql_library_end()"><code class="literal">mysql_library_end()</code></a> performs
          some memory management to clean up. For an embedded server
          application linked against the <code class="literal">libmysqld</code>
          library by using the <code class="option">-lmysqld</code> flag,
          <a class="link" href="connectors-apis.html#mysql-library-end" title="27.8.7.40 mysql_library_end()"><code class="literal">mysql_library_end()</code></a> shuts down
          the embedded server and then cleans up.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
            To avoid memory leaks after the application is done using
            the library (for example, after closing the connection to
            the server), be sure to call
            <a class="link" href="connectors-apis.html#mysql-library-end" title="27.8.7.40 mysql_library_end()"><code class="literal">mysql_library_end()</code></a>
            explicitly. This enables memory managment to be performed to
            clean up and free resources used by the library.
</p>
</div>
<p>
          For usage information, see
          <a class="xref" href="connectors-apis.html#c-api-function-overview" title="27.8.6 C API Function Overview">Section 27.8.6, “C API Function Overview”</a>, and
          <a class="xref" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()">Section 27.8.7.41, “mysql_library_init()”</a>.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-library-init"></a>27.8.7.41 mysql_library_init()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574553296"></a><p>
        <code class="literal">int mysql_library_init(int argc, char **argv, char
        **groups)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-library-init-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Call this function to initialize the MySQL client library
          before you call any other MySQL function, whether your
          application is a regular client program or uses the embedded
          server. If the application uses the embedded server, this call
          starts the server and initializes any subsystems
          (<code class="literal">mysys</code>, <code class="literal">InnoDB</code>, and so
          forth) that the server uses.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
            To avoid memory leaks after the application is done using
            the library (for example, after closing the connection to
            the server), be sure to call
            <a class="link" href="connectors-apis.html#mysql-library-end" title="27.8.7.40 mysql_library_end()"><code class="literal">mysql_library_end()</code></a>
            explicitly. This enables memory managment to be performed to
            clean up and free resources used by the library. See
            <a class="xref" href="connectors-apis.html#mysql-library-end" title="27.8.7.40 mysql_library_end()">Section 27.8.7.40, “mysql_library_end()”</a>.
</p>
</div>
<p>
          The choice of whether the application operates as a regular
          client or uses the embedded server depends on whether you use
          the <code class="literal">libmysqlclient</code> or
          <code class="literal">libmysqld</code> library at link time to produce
          the final executable. For additional information, see
          <a class="xref" href="connectors-apis.html#c-api-function-overview" title="27.8.6 C API Function Overview">Section 27.8.6, “C API Function Overview”</a>.
        </p><p>
          In a nonmulti-threaded environment, the call to
          <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a> may be
          omitted, because <a class="link" href="connectors-apis.html#mysql-init" title="27.8.7.37 mysql_init()"><code class="literal">mysql_init()</code></a>
          will invoke it automatically as necessary. However,
          <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a> is not
          thread-safe in a multi-threaded environment, and thus neither
          is <a class="link" href="connectors-apis.html#mysql-init" title="27.8.7.37 mysql_init()"><code class="literal">mysql_init()</code></a>, which calls
          <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a>. You must
          either call
          <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a> prior to
          spawning any threads, or else use a mutex to protect the call,
          whether you invoke
          <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a> or
          indirectly through
          <a class="link" href="connectors-apis.html#mysql-init" title="27.8.7.37 mysql_init()"><code class="literal">mysql_init()</code></a>. Do this prior to
          any other client library call.
        </p><p>
          The <code class="literal">argc</code> and <code class="literal">argv</code>
          arguments are analogous to the arguments to
          <code class="literal">main()</code>, and enable passing of options to
          the embedded server. For convenience, <code class="literal">argc</code>
          may be <code class="literal">0</code> (zero) if there are no
          command-line arguments for the server. This is the usual case
          for applications intended for use only as regular
          (nonembedded) clients, and the call typically is written as
          <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init(0, NULL,
          NULL)</code></a>.
        </p><pre data-lang="c" class="programlisting">
#include &lt;mysql.h&gt;
#include &lt;stdlib.h&gt;

int main(void) {
  if (mysql_library_init(0, NULL, NULL)) {
    fprintf(stderr, "could not initialize MySQL client library\n");
    exit(1);
  }

  /* Use any MySQL API functions here */

  mysql_library_end();

  return EXIT_SUCCESS;
}
</pre><p>
          When arguments are to be passed (<code class="literal">argc</code> is
          greater than <code class="literal">0</code>), the first element of
          <code class="literal">argv</code> is ignored (it typically contains the
          program name).
          <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a> makes a
          copy of the arguments so it is safe to destroy
          <code class="literal">argv</code> or <code class="literal">groups</code> after the
          call.
        </p><p>
          For embedded applications, if you want to connect to an
          external server without starting the embedded server, you have
          to specify a negative value for <code class="literal">argc</code>.
        </p><p>
          The <code class="literal">groups</code> argument is an array of strings
          that indicate the groups in option files from which to read
          options. See <a class="xref" href="programs.html#option-files" title="4.2.6 Using Option Files">Section 4.2.6, “Using Option Files”</a>. Make the final
          entry in the array <code class="literal">NULL</code>. For convenience,
          if the <code class="literal">groups</code> argument itself is
          <code class="literal">NULL</code>, the <code class="literal">[server]</code> and
          <code class="literal">[embedded]</code> groups are used by default.
        </p><pre data-lang="c" class="programlisting">
#include &lt;mysql.h&gt;
#include &lt;stdlib.h&gt;

static char *server_args[] = {
  "this_program",       /* this string is not used */
  "--datadir=.",
  "--key_buffer_size=32M"
};
static char *server_groups[] = {
  "embedded",
  "server",
  "this_program_SERVER",
  (char *)NULL
};

int main(void) {
  if (mysql_library_init(sizeof(server_args) / sizeof(char *),
                        server_args, server_groups)) {
    fprintf(stderr, "could not initialize MySQL client library\n");
    exit(1);
  }

  /* Use any MySQL API functions here */

  mysql_library_end();

  return EXIT_SUCCESS;
}
</pre>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-library-init-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-list-dbs"></a>27.8.7.42 mysql_list_dbs()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574506592"></a><p>
        <code class="literal">MYSQL_RES *mysql_list_dbs(MYSQL *mysql, const char
        *wild)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-list-dbs-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns a result set consisting of database names on the
          server that match the simple regular expression specified by
          the <code class="literal">wild</code> parameter. <code class="literal">wild</code>
          may contain the wildcard characters <code class="literal">%</code> or
          <code class="literal">_</code>, or may be a <code class="literal">NULL</code>
          pointer to match all databases. Calling
          <a class="link" href="connectors-apis.html#mysql-list-dbs" title="27.8.7.42 mysql_list_dbs()"><code class="literal">mysql_list_dbs()</code></a> is similar to
          executing the query <code class="literal">SHOW DATABASES [LIKE
          <em class="replaceable"><code>wild</code></em>]</code>.
        </p><p>
          You must free the result set with
          <a class="link" href="connectors-apis.html#mysql-free-result" title="27.8.7.25 mysql_free_result()"><code class="literal">mysql_free_result()</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-list-dbs-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          A <code class="literal">MYSQL_RES</code> result set for success.
          <code class="literal">NULL</code> if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-list-dbs-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_out_of_memory"><code class="literal">CR_OUT_OF_MEMORY</code></a>
            </p><p>
              Out of memory.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-list-fields"></a>27.8.7.43 mysql_list_fields()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574476496"></a><p>
        <code class="literal">MYSQL_RES *mysql_list_fields(MYSQL *mysql, const char
        *table, const char *wild)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-list-fields-description"></a>Description</h5>

</div>

</div>

</div>

<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
            As of MySQL 5.7.11, <code class="literal">mysql_list_fields()</code>
            is deprecated and will be removed in a future version of
            MySQL. Instead, use
            <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a> to execute a
            <a class="link" href="sql-syntax.html#show-columns" title="13.7.5.5 SHOW COLUMNS Syntax"><code class="literal">SHOW COLUMNS</code></a> statement.
</p>
</div>
<p>
          Returns an empty result set for which the metadata provides
          information about the columns in the given table that match
          the simple regular expression specified by the
          <code class="literal">wild</code> parameter. <code class="literal">wild</code> may
          contain the wildcard characters <code class="literal">%</code> or
          <code class="literal">_</code>, or may be a <code class="literal">NULL</code>
          pointer to match all fields. Calling
          <a class="link" href="connectors-apis.html#mysql-list-fields" title="27.8.7.43 mysql_list_fields()"><code class="literal">mysql_list_fields()</code></a> is similar
          to executing the query <code class="literal">SHOW COLUMNS FROM
          <em class="replaceable"><code>tbl_name</code></em> [LIKE
          <em class="replaceable"><code>wild</code></em>]</code>.
        </p><p>
          It is preferable to use <code class="literal">SHOW COLUMNS FROM
          <em class="replaceable"><code>tbl_name</code></em></code> instead of
          <a class="link" href="connectors-apis.html#mysql-list-fields" title="27.8.7.43 mysql_list_fields()"><code class="literal">mysql_list_fields()</code></a>.
        </p><p>
          You must free the result set with
          <a class="link" href="connectors-apis.html#mysql-free-result" title="27.8.7.25 mysql_free_result()"><code class="literal">mysql_free_result()</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-list-fields-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          A <code class="literal">MYSQL_RES</code> result set for success.
          <code class="literal">NULL</code> if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-list-fields-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-list-fields-example"></a>Example</h5>

</div>

</div>

</div>
<pre data-lang="c" class="programlisting">
int i;
MYSQL_RES *tbl_cols = mysql_list_fields(mysql, "mytbl", "f%");

unsigned int field_cnt = mysql_num_fields(tbl_cols);
printf("Number of columns: %d\n", field_cnt);

for (i=0; i &lt; field_cnt; ++i)
{
  /* col describes i-th column of the table */
  MYSQL_FIELD *col = mysql_fetch_field_direct(tbl_cols, i);
  printf ("Column %d: %s\n", i, col-&gt;name);
}
mysql_free_result(tbl_cols);
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-list-processes"></a>27.8.7.44 mysql_list_processes()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574438512"></a><p>
        <code class="literal">MYSQL_RES *mysql_list_processes(MYSQL *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-list-processes-description"></a>Description</h5>

</div>

</div>

</div>

<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
            As of MySQL 5.7.11,
            <code class="literal">mysql_list_processes()</code> is deprecated and
            will be removed in a future version of MySQL. Instead, use
            <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a> to execute a
            <a class="link" href="sql-syntax.html#show-processlist" title="13.7.5.29 SHOW PROCESSLIST Syntax"><code class="literal">SHOW PROCESSLIST</code></a> statement.
</p>
</div>
<p>
          Returns a result set describing the current server threads.
          This is the same kind of information as that reported by
          <a class="link" href="programs.html#mysqladmin" title="4.5.2 mysqladmin — Client for Administering a MySQL Server"><span class="command"><strong>mysqladmin processlist</strong></span></a> or a
          <a class="link" href="sql-syntax.html#show-processlist" title="13.7.5.29 SHOW PROCESSLIST Syntax"><code class="literal">SHOW PROCESSLIST</code></a> query.
        </p><p>
          You must free the result set with
          <a class="link" href="connectors-apis.html#mysql-free-result" title="27.8.7.25 mysql_free_result()"><code class="literal">mysql_free_result()</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-list-processes-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          A <code class="literal">MYSQL_RES</code> result set for success.
          <code class="literal">NULL</code> if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-list-processes-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-list-tables"></a>27.8.7.45 mysql_list_tables()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574410464"></a><p>
        <code class="literal">MYSQL_RES *mysql_list_tables(MYSQL *mysql, const char
        *wild)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-list-tables-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns a result set consisting of table names in the current
          database that match the simple regular expression specified by
          the <code class="literal">wild</code> parameter. <code class="literal">wild</code>
          may contain the wildcard characters <code class="literal">%</code> or
          <code class="literal">_</code>, or may be a <code class="literal">NULL</code>
          pointer to match all tables. Calling
          <a class="link" href="connectors-apis.html#mysql-list-tables" title="27.8.7.45 mysql_list_tables()"><code class="literal">mysql_list_tables()</code></a> is similar
          to executing the query <code class="literal">SHOW TABLES [LIKE
          <em class="replaceable"><code>wild</code></em>]</code>.
        </p><p>
          You must free the result set with
          <a class="link" href="connectors-apis.html#mysql-free-result" title="27.8.7.25 mysql_free_result()"><code class="literal">mysql_free_result()</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-list-tables-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          A <code class="literal">MYSQL_RES</code> result set for success.
          <code class="literal">NULL</code> if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-list-tables-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-more-results"></a>27.8.7.46 mysql_more_results()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574382944"></a><p>
        <code class="literal">my_bool mysql_more_results(MYSQL *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-more-results-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          This function is used when you execute multiple statements
          specified as a single statement string, or when you execute
          <a class="link" href="sql-syntax.html#call" title="13.2.1 CALL Syntax"><code class="literal">CALL</code></a> statements, which can
          return multiple result sets.
        </p><p>
          <a class="link" href="connectors-apis.html#mysql-more-results" title="27.8.7.46 mysql_more_results()"><code class="literal">mysql_more_results()</code></a> true if
          more results exist from the currently executed statement, in
          which case the application must call
          <a class="link" href="connectors-apis.html#mysql-next-result" title="27.8.7.47 mysql_next_result()"><code class="literal">mysql_next_result()</code></a> to fetch
          the results.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-more-results-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          <code class="literal">TRUE</code> (1) if more results exist.
          <code class="literal">FALSE</code> (0) if no more results exist.
        </p><p>
          In most cases, you can call
          <a class="link" href="connectors-apis.html#mysql-next-result" title="27.8.7.47 mysql_next_result()"><code class="literal">mysql_next_result()</code></a> instead to
          test whether more results exist and initiate retrieval if so.
        </p><p>
          See <a class="xref" href="connectors-apis.html#c-api-multiple-queries" title="27.8.16 C API Multiple Statement Execution Support">Section 27.8.16, “C API Multiple Statement Execution Support”</a>, and
          <a class="xref" href="connectors-apis.html#mysql-next-result" title="27.8.7.47 mysql_next_result()">Section 27.8.7.47, “mysql_next_result()”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-more-results-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-next-result"></a>27.8.7.47 mysql_next_result()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574365216"></a><p>
        <code class="literal">int mysql_next_result(MYSQL *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-next-result-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          This function is used when you execute multiple statements
          specified as a single statement string, or when you use
          <a class="link" href="sql-syntax.html#call" title="13.2.1 CALL Syntax"><code class="literal">CALL</code></a> statements to execute
          stored procedures, which can return multiple result sets.
        </p><p>
          <a class="link" href="connectors-apis.html#mysql-next-result" title="27.8.7.47 mysql_next_result()"><code class="literal">mysql_next_result()</code></a> reads the
          next statement result and returns a status to indicate whether
          more results exist. If
          <a class="link" href="connectors-apis.html#mysql-next-result" title="27.8.7.47 mysql_next_result()"><code class="literal">mysql_next_result()</code></a> returns an
          error, there are no more results.
        </p><p>
          Before each call to
          <a class="link" href="connectors-apis.html#mysql-next-result" title="27.8.7.47 mysql_next_result()"><code class="literal">mysql_next_result()</code></a>, you must
          call <a class="link" href="connectors-apis.html#mysql-free-result" title="27.8.7.25 mysql_free_result()"><code class="literal">mysql_free_result()</code></a> for
          the current statement if it is a statement that returned a
          result set (rather than just a result status).
        </p><p>
          After calling
          <a class="link" href="connectors-apis.html#mysql-next-result" title="27.8.7.47 mysql_next_result()"><code class="literal">mysql_next_result()</code></a> the state
          of the connection is as if you had called
          <a class="link" href="connectors-apis.html#mysql-real-query" title="27.8.7.57 mysql_real_query()"><code class="literal">mysql_real_query()</code></a> or
          <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a> for the next
          statement. This means that you can call
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a>,
          <a class="link" href="connectors-apis.html#mysql-warning-count" title="27.8.7.78 mysql_warning_count()"><code class="literal">mysql_warning_count()</code></a>,
          <a class="link" href="connectors-apis.html#mysql-affected-rows" title="27.8.7.1 mysql_affected_rows()"><code class="literal">mysql_affected_rows()</code></a>, and so
          forth.
        </p><p>
          If your program uses <a class="link" href="sql-syntax.html#call" title="13.2.1 CALL Syntax"><code class="literal">CALL</code></a>
          statements to execute stored procedures, the
          <code class="literal">CLIENT_MULTI_RESULTS</code> flag must be enabled.
          This is because each <a class="link" href="sql-syntax.html#call" title="13.2.1 CALL Syntax"><code class="literal">CALL</code></a>
          returns a result to indicate the call status, in addition to
          any result sets that might be returned by statements executed
          within the procedure. Because
          <a class="link" href="sql-syntax.html#call" title="13.2.1 CALL Syntax"><code class="literal">CALL</code></a> can return multiple
          results, process them using a loop that calls
          <a class="link" href="connectors-apis.html#mysql-next-result" title="27.8.7.47 mysql_next_result()"><code class="literal">mysql_next_result()</code></a> to
          determine whether there are more results.
        </p><p>
          <code class="literal">CLIENT_MULTI_RESULTS</code> can be enabled when
          you call <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a>,
          either explicitly by passing the
          <code class="literal">CLIENT_MULTI_RESULTS</code> flag itself, or
          implicitly by passing
          <code class="literal">CLIENT_MULTI_STATEMENTS</code> (which also enables
          <code class="literal">CLIENT_MULTI_RESULTS</code>). In MySQL
          5.7, <code class="literal">CLIENT_MULTI_RESULTS</code> is
          enabled by default.
        </p><p>
          It is also possible to test whether there are more results by
          calling <a class="link" href="connectors-apis.html#mysql-more-results" title="27.8.7.46 mysql_more_results()"><code class="literal">mysql_more_results()</code></a>.
          However, this function does not change the connection state,
          so if it returns true, you must still call
          <a class="link" href="connectors-apis.html#mysql-next-result" title="27.8.7.47 mysql_next_result()"><code class="literal">mysql_next_result()</code></a> to advance
          to the next result.
        </p><p>
          For an example that shows how to use
          <a class="link" href="connectors-apis.html#mysql-next-result" title="27.8.7.47 mysql_next_result()"><code class="literal">mysql_next_result()</code></a>, see
          <a class="xref" href="connectors-apis.html#c-api-multiple-queries" title="27.8.16 C API Multiple Statement Execution Support">Section 27.8.16, “C API Multiple Statement Execution Support”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-next-result-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<div class="informaltable">
<table summary="mysql_next_result() return values and a description of each value."><col width="35%"><col width="65%"><thead><tr>
              <th scope="col">Return Value</th>
              <th scope="col">Description</th>
            </tr></thead><tbody><tr>
              <td scope="row">0</td>
              <td>Successful and there are more results</td>
            </tr><tr>
              <td scope="row">-1</td>
              <td>Successful and there are no more results</td>
            </tr><tr>
              <td scope="row">&gt;0</td>
              <td>An error occurred</td>
</tr></tbody></table>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-next-result-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order. For example,
              if you did not call
              <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a> for a
              previous result set.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-num-fields"></a>27.8.7.48 mysql_num_fields()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574300512"></a><a class="indexterm" name="idm140710574299440"></a><p>
        <code class="literal">unsigned int mysql_num_fields(MYSQL_RES
        *result)</code>
      </p><p>
        To pass a <code class="literal">MYSQL*</code> argument instead, use
        <code class="literal">unsigned int mysql_field_count(MYSQL *mysql)</code>.
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-num-fields-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns the number of columns in a result set.
        </p><p>
          You can get the number of columns either from a pointer to a
          result set or to a connection handler. You would use the
          connection handler if
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a> or
          <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a> returned
          <code class="literal">NULL</code> (and thus you have no result set
          pointer). In this case, you can call
          <a class="link" href="connectors-apis.html#mysql-field-count" title="27.8.7.22 mysql_field_count()"><code class="literal">mysql_field_count()</code></a> to
          determine whether
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a> should
          have produced a nonempty result. This enables the client
          program to take proper action without knowing whether the
          query was a <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a> (or
          <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a>-like) statement. The
          example shown here illustrates how this may be done.
        </p><p>
          See <a class="xref" href="connectors-apis.html#null-mysql-store-result" title="27.8.21.1 Why mysql_store_result() Sometimes Returns NULL After mysql_query() Returns Success">Section 27.8.21.1, “Why mysql_store_result() Sometimes Returns NULL After mysql_query()
        Returns Success”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-num-fields-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          An unsigned integer representing the number of columns in a
          result set.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-num-fields-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-num-fields-example"></a>Example</h5>

</div>

</div>

</div>
<pre data-lang="c" class="programlisting">
MYSQL_RES *result;
unsigned int num_fields;
unsigned int num_rows;

if (mysql_query(&amp;mysql,query_string))
{
    // error
}
else // query succeeded, process any data returned by it
{
    result = mysql_store_result(&amp;mysql);
    if (result)  // there are rows
    {
        num_fields = mysql_num_fields(result);
        // retrieve rows, then call mysql_free_result(result)
    }
    else  // mysql_store_result() returned nothing; should it have?
    {
        if (mysql_errno(&amp;mysql))
        {
           fprintf(stderr, "Error: %s\n", mysql_error(&amp;mysql));
        }
        else if (mysql_field_count(&amp;mysql) == 0)
        {
            // query does not return data
            // (it was not a SELECT)
            num_rows = mysql_affected_rows(&amp;mysql);
        }
    }
}
</pre><p>
          An alternative (if you know that your query should have
          returned a result set) is to replace the
          <a class="link" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()"><code class="literal">mysql_errno(&amp;mysql)</code></a> call
          with a check whether
          <a class="link" href="connectors-apis.html#mysql-field-count" title="27.8.7.22 mysql_field_count()"><code class="literal">mysql_field_count(&amp;mysql)</code></a>
          returns 0. This happens only if something went wrong.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-num-rows"></a>27.8.7.49 mysql_num_rows()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574272240"></a><p>
        <code class="literal">my_ulonglong mysql_num_rows(MYSQL_RES
        *result)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-num-rows-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns the number of rows in the result set.
        </p><p>
          The use of <a class="link" href="connectors-apis.html#mysql-num-rows" title="27.8.7.49 mysql_num_rows()"><code class="literal">mysql_num_rows()</code></a>
          depends on whether you use
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a> or
          <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a> to return
          the result set. If you use
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a>,
          <a class="link" href="connectors-apis.html#mysql-num-rows" title="27.8.7.49 mysql_num_rows()"><code class="literal">mysql_num_rows()</code></a> may be called
          immediately. If you use
          <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a>,
          <a class="link" href="connectors-apis.html#mysql-num-rows" title="27.8.7.49 mysql_num_rows()"><code class="literal">mysql_num_rows()</code></a> does not
          return the correct value until all the rows in the result set
          have been retrieved.
        </p><p>
          <a class="link" href="connectors-apis.html#mysql-num-rows" title="27.8.7.49 mysql_num_rows()"><code class="literal">mysql_num_rows()</code></a> is intended
          for use with statements that return a result set, such as
          <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a>. For statements such as
          <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT</code></a>,
          <a class="link" href="sql-syntax.html#update" title="13.2.11 UPDATE Syntax"><code class="literal">UPDATE</code></a>, or
          <a class="link" href="sql-syntax.html#delete" title="13.2.2 DELETE Syntax"><code class="literal">DELETE</code></a>, the number of affected
          rows can be obtained with
          <a class="link" href="connectors-apis.html#mysql-affected-rows" title="27.8.7.1 mysql_affected_rows()"><code class="literal">mysql_affected_rows()</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-num-rows-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          The number of rows in the result set.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-num-rows-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-options"></a>27.8.7.50 mysql_options()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710574246432"></a><p>
        <code class="literal">int mysql_options(MYSQL *mysql, enum mysql_option
        option, const void *arg)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-options-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Can be used to set extra connect options and affect behavior
          for a connection. This function may be called multiple times
          to set several options. To retrieve option values, use
          <a class="link" href="connectors-apis.html#mysql-get-option" title="27.8.7.30 mysql_get_option()"><code class="literal">mysql_get_option()</code></a>.
        </p><p>
          Call <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> after
          <a class="link" href="connectors-apis.html#mysql-init" title="27.8.7.37 mysql_init()"><code class="literal">mysql_init()</code></a> and before
          <a class="link" href="connectors-apis.html#mysql-connect" title="27.8.7.7 mysql_connect()"><code class="literal">mysql_connect()</code></a> or
          <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a>.
        </p><p>
          The <code class="literal">option</code> argument is the option that you
          want to set; the <code class="literal">arg</code> argument is the value
          for the option. If the option is an integer, specify a pointer
          to the value of the integer as the <code class="literal">arg</code>
          argument.
        </p><p>
          Options for information such as SSL certificate and key files
          are used to establish an encrypted connection if such
          connections are available, but do not enforce any requirement
          that the connection obtained be encrypted. To require an
          encrypted connection, use the technique described in
          <a class="xref" href="connectors-apis.html#c-api-encrypted-connections" title="27.8.15 C API Encrypted Connection Support">Section 27.8.15, “C API Encrypted Connection Support”</a>.
        </p><p>
          The following list describes the possible options, their
          effect, and how <code class="literal">arg</code> is used for each
          option. For option descriptions that indicate
          <code class="literal">arg</code> is unused, its value is irrelevant; it
          is conventional to pass 0. Several of the options apply only
          when the application is linked against the
          <code class="literal">libmysqld</code> embedded server library and are
          unused for applications linked against the
          <code class="literal">libmysqlclient</code> client library.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <code class="literal">MYSQL_DEFAULT_AUTH</code> (argument type:
              <code class="literal">char *</code>)
            </p><p>
              The name of the authentication plugin to use.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_ENABLE_CLEARTEXT_PLUGIN</code> (argument
              type: <code class="literal">my_bool *</code>)
            </p><p>
              Enable the <code class="literal">mysql_clear_password</code>
              cleartext authentication plugin. See
              <a class="xref" href="security.html#cleartext-pluggable-authentication" title="6.5.1.5 Client-Side Cleartext Pluggable Authentication">Section 6.5.1.5, “Client-Side Cleartext Pluggable Authentication”</a>.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_INIT_COMMAND</code> (argument type:
              <code class="literal">char *</code>)
            </p><p>
              SQL statement to execute when connecting to the MySQL
              server. Automatically re-executed if reconnection occurs.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_BIND</code> (argument: <code class="literal">char
              *</code>)
            </p><p>
              The network interface from which to connect to the server.
              This is used when the client host has multiple network
              interfaces. The argument is a host name or IP address
              (specified as a string).
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS</code>
              (argument type: <code class="literal">my_bool *</code>)
            </p><p>
              Indicate whether the client can handle expired passwords.
              See <a class="xref" href="security.html#expired-password-handling" title="6.3.8 Password Expiration and Sandbox Mode">Section 6.3.8, “Password Expiration and Sandbox Mode”</a>.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_COMPRESS</code> (argument: not used)
            </p><p>
              Use the compressed client/server protocol.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_CONNECT_ATTR_DELETE</code> (argument
              type: <code class="literal">char *</code>)
            </p><p>
              Given a key name, this option deletes a key/value pair
              from the current set of connection attributes to pass to
              the server at connect time. The argument is a pointer to a
              null-terminated string naming the key. Comparison of the
              key name with existing keys is case-sensitive.
            </p><p>
              See also the description for the
              <code class="literal">MYSQL_OPT_CONNECT_ATTR_RESET</code> option, as
              well as the description for the
              <code class="literal">MYSQL_OPT_CONNECT_ATTR_ADD</code> option in
              the description of the
              <a class="link" href="connectors-apis.html#mysql-options4" title="27.8.7.51 mysql_options4()"><code class="literal">mysql_options4()</code></a> function.
              That function description also includes a usage example.
            </p><p>
              The Performance Schema exposes connection attributes
              through the
              <a class="link" href="performance-schema.html#session-connect-attrs-table" title="25.11.9.2 The session_connect_attrs Table"><code class="literal">session_connect_attrs</code></a> and
              <a class="link" href="performance-schema.html#session-account-connect-attrs-table" title="25.11.9.1 The session_account_connect_attrs Table"><code class="literal">session_account_connect_attrs</code></a>
              tables. See
              <a class="xref" href="performance-schema.html#performance-schema-connection-attribute-tables" title="25.11.9 Performance Schema Connection Attribute Tables">Section 25.11.9, “Performance Schema Connection Attribute Tables”</a>.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_CONNECT_ATTR_RESET</code> (argument
              not used)
            </p><p>
              This option resets (clears) the current set of connection
              attributes to pass to the server at connect time.
            </p><p>
              See also the description for the
              <code class="literal">MYSQL_OPT_CONNECT_ATTR_DELETE</code> option,
              as well as the description for the
              <code class="literal">MYSQL_OPT_CONNECT_ATTR_ADD</code> option in
              the description of the
              <a class="link" href="connectors-apis.html#mysql-options4" title="27.8.7.51 mysql_options4()"><code class="literal">mysql_options4()</code></a> function.
              That function description also includes a usage example.
            </p><p>
              The Performance Schema exposes connection attributes
              through the
              <a class="link" href="performance-schema.html#session-connect-attrs-table" title="25.11.9.2 The session_connect_attrs Table"><code class="literal">session_connect_attrs</code></a> and
              <a class="link" href="performance-schema.html#session-account-connect-attrs-table" title="25.11.9.1 The session_account_connect_attrs Table"><code class="literal">session_account_connect_attrs</code></a>
              tables. See
              <a class="xref" href="performance-schema.html#performance-schema-connection-attribute-tables" title="25.11.9 Performance Schema Connection Attribute Tables">Section 25.11.9, “Performance Schema Connection Attribute Tables”</a>.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_CONNECT_TIMEOUT</code> (argument
              type: <code class="literal">unsigned int *</code>)
            </p><p>
              The connect timeout in seconds.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_GUESS_CONNECTION</code> (argument:
              not used)
            </p><p>
              For an application linked against the
              <code class="literal">libmysqld</code> embedded server library, this
              option enables the library to guess whether to use the
              embedded server or a remote server. <span class="quote">“<span class="quote">Guess</span>”</span>
              means that if the host name is set and is not
              <code class="literal">localhost</code>, it uses a remote server.
              This behavior is the default.
              <code class="literal">MYSQL_OPT_USE_EMBEDDED_CONNECTION</code> and
              <code class="literal">MYSQL_OPT_USE_REMOTE_CONNECTION</code> can be
              used to override it. This option is ignored for
              applications linked against the
              <code class="literal">libmysqlclient</code> client library.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_LOCAL_INFILE</code> (argument type:
              optional pointer to <code class="literal">unsigned int</code>)
            </p><p>
              This option affects client-side <code class="literal">LOCAL</code>
              capability for <a class="link" href="sql-syntax.html#load-data" title="13.2.6 LOAD DATA INFILE Syntax"><code class="literal">LOAD DATA</code></a>
              operations. By default, <code class="literal">LOCAL</code>
              capability is determined by the default compiled into the
              MySQL client library (see <a class="xref" href="sql-syntax.html#load-data" title="13.2.6 LOAD DATA INFILE Syntax">Section 13.2.6, “LOAD DATA INFILE Syntax”</a>). To
              control this capability explicitly, invoke
              <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> to set the
              <code class="literal">MYSQL_OPT_LOCAL_INFILE</code> option:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                  <code class="literal">LOCAL</code> is disabled if the pointer
                  points to an <code class="literal">unsigned int</code> that has
                  a zero value.
                </p></li><li class="listitem"><p>
                  <code class="literal">LOCAL</code> is enabled if no pointer is
                  given or if the pointer points to an <code class="literal">unsigned
                  int</code> that has a nonzero value.
</p></li></ul>
</div>
<p>
              Successful use of a <code class="literal">LOCAL</code> load
              operation by a client also requires that the server
              permits it.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_MAX_ALLOWED_PACKET</code> (argument:
              <code class="literal">unsigned long *</code>)
            </p><p>
              This option sets the
              <a class="link" href="server-administration.html#sysvar_max_allowed_packet"><code class="literal">max_allowed_packet</code></a> system
              variable. If the <code class="literal">mysql</code> argument is
              non-<code class="literal">NULL</code>, the call sets the session
              system variable value for that session. If
              <code class="literal">mysql</code> is <code class="literal">NULL</code>, the
              call sets the global system variable value.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_NAMED_PIPE</code> (argument: not
              used)
            </p><p>
              Use a named pipe to connect to the MySQL server on
              Windows, if the server permits named-pipe connections.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_NET_BUFFER_LENGTH</code> (argument:
              <code class="literal">unsigned long *</code>)
            </p><p>
              This option sets the
              <a class="link" href="server-administration.html#sysvar_net_buffer_length"><code class="literal">net_buffer_length</code></a> system
              variable. If the <code class="literal">mysql</code> argument is
              non-<code class="literal">NULL</code>, the call sets the session
              system variable value for that session. If
              <code class="literal">mysql</code> is <code class="literal">NULL</code>, the
              call sets the global system variable value.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_PROTOCOL</code> (argument type:
              <code class="literal">unsigned int *</code>)
            </p><p>
              Type of protocol to use. Specify one of the enum values of
              <code class="literal">mysql_protocol_type</code> defined in
              <code class="filename">mysql.h</code>.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_READ_TIMEOUT</code> (argument type:
              <code class="literal">unsigned int *</code>)
            </p><p>
              The timeout in seconds for each attempt to read from the
              server. There are retries if necessary, so the total
              effective timeout value is three times the option value.
              You can set the value so that a lost connection can be
              detected earlier than the TCP/IP
              <code class="literal">Close_Wait_Timeout</code> value of 10 minutes.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_RECONNECT</code> (argument type:
              <code class="literal">my_bool *</code>)
            </p><p>
              Enable or disable automatic reconnection to the server if
              the connection is found to have been lost. Reconnect is
              off by default; this option provides a way to set
              reconnection behavior explicitly. See
              <a class="xref" href="connectors-apis.html#c-api-auto-reconnect" title="27.8.20 C API Automatic Reconnection Control">Section 27.8.20, “C API Automatic Reconnection Control”</a>.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_RETRY_COUNT</code> (argument type:
              <code class="literal">unsigned int *</code>)
            </p><p>
              The retry count for I/O-related system calls that are
              interrupted while connecting to the server or
              communicating with it. The default value is 1 (1 retry if
              the initial call is interrupted for 2 tries total).
            </p><p>
              This option can be used only by clients that link against
              a C client library compiiled with NDB Cluster support. It
              is available as of MySQL NDB Cluster 7.5.1.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_SSL_CA</code> (argument type:
              <code class="literal">char *</code>)
            </p><p>
              The path name of the Certificate Authority (CA)
              certificate file. This option, if used, must specify the
              same certificate used by the server.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_SSL_CAPATH</code> (argument type:
              <code class="literal">char *</code>)
            </p><p>
              The path name of the directory that contains trusted SSL
              CA certificate files.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_SSL_CERT</code> (argument type:
              <code class="literal">char *</code>)
            </p><p>
              The path name of the client public key certificate file.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_SSL_CIPHER</code> (argument type:
              <code class="literal">char *</code>)
            </p><p>
              The list of permitted ciphers for SSL encryption.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_SSL_CRL</code> (argument type:
              <code class="literal">char *</code>)
            </p><p>
              The path name of the file containing certificate
              revocation lists.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_SSL_CRLPATH</code> (argument type:
              <code class="literal">char *</code>)
            </p><p>
              The path name of the directory that contains files
              containing certificate revocation lists.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_SSL_ENFORCE</code> (argument type:
              <code class="literal">my_bool *</code>)
            </p><p>
              Whether to require the connection to use SSL. If enabled
              and an encrypted connection cannot be established, the
              connection attempt fails.
            </p><p>
              This option is deprecated as of MySQL 5.7.11 and is
              removed in MySQL 8.0. Instead, use
              <code class="literal">MYSQL_OPT_SSL_MODE</code> with a value of
              <code class="literal">SSL_MODE_REQUIRED</code>.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_SSL_KEY</code> (argument type:
              <code class="literal">char *</code>)
            </p><p>
              The path name of the client private key file.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_SSL_MODE</code> (argument type:
              <code class="literal">unsigned int *</code>)
            </p><p>
              The security state to use for the connection to the
              server: <code class="literal">SSL_MODE_DISABLED</code>,
              <code class="literal">SSL_MODE_PREFERRED</code>,
              <code class="literal">SSL_MODE_REQUIRED</code>,
              <code class="literal">SSL_MODE_VERIFY_CA</code>,
              <code class="literal">SSL_MODE_VERIFY_IDENTITY</code>. The default
              is <code class="literal">SSL_MODE_PREFERRED</code>. These modes are
              the permitted values of the
              <code class="literal">mysql_ssl_mode</code> enumeration defined in
              <code class="filename">mysql.h</code>. For more information about
              the security states, see the description of
              <a class="link" href="security.html#option_general_ssl-mode"><code class="option">--ssl-mode</code></a> in
              <a class="xref" href="security.html#encrypted-connection-options" title="6.4.2 Command Options for Encrypted Connections">Section 6.4.2, “Command Options for Encrypted Connections”</a>.
            </p><p>
              This option was added in MySQL 5.7.11.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_SSL_VERIFY_SERVER_CERT</code>
              (argument type: <code class="literal">my_bool *</code>)
            </p><p>
              Enable or disable verification of the server's Common Name
              identity in its certificate against the host name used
              when connecting to the server. The connection is rejected
              if there is a mismatch. For encrypted connections, this
              feature can be used to prevent man-in-the-middle attacks.
              Identity verification is disabled by default.
            </p><p>
              This option does not work with self-signed certificates,
              which do not contain the server name as the Common Name
              value.
            </p><p>
              This option is deprecated as of MySQL 5.7.11 and is
              removed in MySQL 8.0. Instead, use
              <code class="literal">MYSQL_OPT_SSL_MODE</code> with a value of
              <code class="literal">SSL_MODE_VERIFY_IDENTITY</code>.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_TLS_VERSION</code> (argument type:
              <code class="literal">char *</code>)
            </p><p>
              The protocols permitted by the client for encrypted
              connections. The value is a comma-separated list
              containing one or more protocol names. The protocols that
              can be named for this option depend on the SSL library
              used to compile MySQL. For details, see
              <a class="xref" href="security.html#encrypted-connection-protocols-ciphers" title="6.4.6 Encrypted Connection Protocols and Ciphers">Section 6.4.6, “Encrypted Connection Protocols and Ciphers”</a>.
            </p><p>
              This option was added in MySQL 5.7.10.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_USE_EMBEDDED_CONNECTION</code>
              (argument: not used)
            </p><p>
              For an application linked against the
              <code class="literal">libmysqld</code> embedded server library, this
              option forces the use of the embedded server for the
              connection. It is ignored for applications linked against
              the <code class="literal">libmysqlclient</code> client library.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_USE_REMOTE_CONNECTION</code>
              (argument: not used)
            </p><p>
              For an application linked against the
              <code class="literal">libmysqld</code> embedded server library, this
              option forces the use of a remote server for the
              connection. It is ignored for applications linked against
              the <code class="literal">libmysqlclient</code> client library.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_USE_RESULT</code> (argument: not
              used)
            </p><p>
              This option is unused.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_WRITE_TIMEOUT</code> (argument type:
              <code class="literal">unsigned int *</code>)
            </p><p>
              The timeout in seconds for each attempt to write to the
              server. There is a retry if necessary, so the total
              effective timeout value is two times the option value.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_PLUGIN_DIR</code> (argument type:
              <code class="literal">char *</code>)
            </p><p>
              The directory in which to look for client plugins.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_READ_DEFAULT_FILE</code> (argument type:
              <code class="literal">char *</code>)
            </p><p>
              Read options from the named option file instead of from
              <code class="filename">my.cnf</code>.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_READ_DEFAULT_GROUP</code> (argument
              type: <code class="literal">char *</code>)
            </p><p>
              Read options from the named group from
              <code class="filename">my.cnf</code> or the file specified with
              <code class="literal">MYSQL_READ_DEFAULT_FILE</code>.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_REPORT_DATA_TRUNCATION</code> (argument
              type: <code class="literal">my_bool *</code>)
            </p><p>
              Enable or disable reporting of data truncation errors for
              prepared statements using the <code class="literal">error</code>
              member of <code class="literal">MYSQL_BIND</code> structures.
              (Default: enabled.)
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_SECURE_AUTH</code> (argument type:
              <code class="literal">my_bool *</code>)
            </p><p>
              Whether to connect to a server that does not support the
              password hashing used in MySQL 4.1.1 and later. This
              option is enabled by default.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_SERVER_PUBLIC_KEY</code> (argument type:
              <code class="literal">char *</code>)
            </p><p>
              The path name to a file containing a client-side copy of
              the public key required by the server for RSA key
              pair-based password exchange. The file must be in PEM
              format. This option applies to clients that authenticate
              with the <code class="literal">sha256_password</code> authentication
              plugin. This option is ignored for accounts that do not
              authenticate with one of those plugins. It is also ignored
              if RSA-based password exchange is not used, as is the case
              when the client connects to the server using a secure
              connection.
            </p><p>
              For information about the
              <code class="literal">sha256_password</code> plugin, see
              <a class="xref" href="security.html#sha256-pluggable-authentication" title="6.5.1.4 SHA-256 Pluggable Authentication">Section 6.5.1.4, “SHA-256 Pluggable Authentication”</a>.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_SET_CHARSET_DIR</code> (argument type:
              <code class="literal">char *</code>)
            </p><p>
              The path name of the directory that contains character set
              definition files.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_SET_CHARSET_NAME</code> (argument type:
              <code class="literal">char *</code>)
            </p><p>
              The name of the character set to use as the default
              character set. The argument can be
              <code class="literal">MYSQL_AUTODETECT_CHARSET_NAME</code> to cause
              the character set to be autodetected based on the
              operating system setting (see
              <a class="xref" href="charset.html#charset-connection" title="10.4 Connection Character Sets and Collations">Section 10.4, “Connection Character Sets and Collations”</a>).
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_SET_CLIENT_IP</code> (argument type:
              <code class="literal">char *</code>)
            </p><p>
              For an application linked against the
              <code class="literal">libmysqld</code> embedded server library (when
              <code class="literal">libmysqld</code> is compiled with
              authentication support), this option means that the user
              is considered to have connected from the specified IP
              address (specified as a string) for authentication
              purposes. It is ignored for applications linked against
              the <code class="literal">libmysqlclient</code> client library.
            </p></li><li class="listitem"><p>
              <code class="literal">MYSQL_SHARED_MEMORY_BASE_NAME</code> (argument
              type: <code class="literal">char *</code>)
            </p><p>
              The name of the shared-memory object for communication to
              the server on Windows, if the server supports
              shared-memory connections. Specify the same value as the
              <a class="link" href="server-administration.html#option_mysqld_shared-memory-base-name"><code class="option">--shared-memory-base-name</code></a>
              option used for the <a class="link" href="programs.html#mysqld" title="4.3.1 mysqld — The MySQL Server"><span class="command"><strong>mysqld</strong></span></a> server you
              want to connect to.
</p></li></ul>
</div>
<p>
          The <code class="literal">client</code> group is always read if you use
          <code class="literal">MYSQL_READ_DEFAULT_FILE</code> or
          <code class="literal">MYSQL_READ_DEFAULT_GROUP</code>.
        </p><p>
          The specified group in the option file may contain the
          following options.
</p>
<div class="informaltable">
<table summary="Options that may appear in the option file and a description of each option."><col width="35%"><col width="65%"><thead><tr>
              <th scope="col">Option</th>
              <th scope="col">Description</th>
            </tr></thead><tbody><tr>
              <td scope="row"><code class="literal">character-sets-dir=<em class="replaceable"><code>dir_name</code></em></code></td>
              <td>The directory where character sets are installed.</td>
            </tr><tr>
              <td scope="row"><code class="literal">compress</code></td>
              <td>Use the compressed client/server protocol.</td>
            </tr><tr>
              <td scope="row"><code class="literal">connect-timeout=<em class="replaceable"><code>seconds</code></em></code></td>
              <td>The connect timeout in seconds. On Linux this timeout is also used for
                waiting for the first answer from the server.</td>
            </tr><tr>
              <td scope="row"><code class="literal">database=<em class="replaceable"><code>db_name</code></em></code></td>
              <td>Connect to this database if no database was specified in the connect
                command.</td>
            </tr><tr>
              <td scope="row"><code class="literal">debug</code></td>
              <td>Debug options.</td>
            </tr><tr>
              <td scope="row"><code class="literal">default-character-set=<em class="replaceable"><code>charset_name</code></em></code></td>
              <td>The default character set to use.</td>
            </tr><tr>
              <td scope="row"><code class="literal">disable-local-infile</code></td>
              <td>Disable use of <a class="link" href="sql-syntax.html#load-data" title="13.2.6 LOAD DATA INFILE Syntax"><code class="literal">LOAD DATA
                LOCAL INFILE</code></a>.</td>
            </tr><tr>
              <td scope="row"><code class="literal">enable-cleartext-plugin</code></td>
              <td>Enable the <code class="literal">mysql_clear_password</code> cleartext
                authentication plugin.</td>
            </tr><tr>
              <td scope="row"><code class="literal">host=<em class="replaceable"><code>host_name</code></em></code></td>
              <td>Default host name.</td>
            </tr><tr>
              <td scope="row"><code class="literal">init-command=<em class="replaceable"><code>stmt</code></em></code></td>
              <td>Statement to execute when connecting to MySQL server. Automatically
                re-executed if reconnection occurs.</td>
            </tr><tr>
              <td scope="row"><code class="literal">interactive-timeout=<em class="replaceable"><code>seconds</code></em></code></td>
              <td>Same as specifying <code class="literal">CLIENT_INTERACTIVE</code> to
                <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a>.
                See <a class="xref" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()">Section 27.8.7.54, “mysql_real_connect()”</a>.</td>
            </tr><tr>
              <td scope="row"><code class="literal">local-infile[={0|1}]</code></td>
              <td>If no argument or nonzero argument, enable use of
                <a class="link" href="sql-syntax.html#load-data" title="13.2.6 LOAD DATA INFILE Syntax"><code class="literal">LOAD DATA
                LOCAL</code></a>; otherwise disable.</td>
            </tr><tr>
              <td scope="row"><code class="literal">max_allowed_packet=<em class="replaceable"><code>bytes</code></em></code></td>
              <td>Maximum size of packet that client can read from server.</td>
            </tr><tr>
              <td scope="row"><code class="literal">multi-queries</code>, <code class="literal">multi-results</code></td>
              <td>Enable multiple result sets from multiple-statement executions or stored
                procedures.</td>
            </tr><tr>
              <td scope="row"><code class="literal">multi-statements</code></td>
              <td>Enable the client to send multiple statements in a single string
                (separated by <code class="literal">;</code> characters).</td>
            </tr><tr>
              <td scope="row"><code class="literal">password=<em class="replaceable"><code>password</code></em></code></td>
              <td>Default password.</td>
            </tr><tr>
              <td scope="row"><code class="literal">pipe</code></td>
              <td>Use named pipes to connect to a MySQL server on Windows.</td>
            </tr><tr>
              <td scope="row"><code class="literal">port=<em class="replaceable"><code>port_num</code></em></code></td>
              <td>Default port number.</td>
            </tr><tr>
              <td scope="row"><code class="literal">protocol={TCP|SOCKET|PIPE|MEMORY}</code></td>
              <td>The protocol to use when connecting to the server.</td>
            </tr><tr>
              <td scope="row"><code class="literal">return-found-rows</code></td>
              <td>Tell <a class="link" href="connectors-apis.html#mysql-info" title="27.8.7.36 mysql_info()"><code class="literal">mysql_info()</code></a> to return found rows
                instead of updated rows when using
                <a class="link" href="sql-syntax.html#update" title="13.2.11 UPDATE Syntax"><code class="literal">UPDATE</code></a>.</td>
            </tr><tr>
              <td scope="row"><code class="literal">shared-memory-base-name=<em class="replaceable"><code>name</code></em></code></td>
              <td>Shared-memory name to use to connect to server.</td>
            </tr><tr>
              <td scope="row"><code class="literal">socket={<em class="replaceable"><code>file_name</code></em>|<em class="replaceable"><code>pipe_name</code></em>}</code></td>
              <td>Default socket file.</td>
            </tr><tr>
              <td scope="row"><code class="literal">ssl-ca=<em class="replaceable"><code>file_name</code></em></code></td>
              <td>Certificate Authority file.</td>
            </tr><tr>
              <td scope="row"><code class="literal">ssl-capath=<em class="replaceable"><code>dir_name</code></em></code></td>
              <td>Certificate Authority directory.</td>
            </tr><tr>
              <td scope="row"><code class="literal">ssl-cert=<em class="replaceable"><code>file_name</code></em></code></td>
              <td>Certificate file.</td>
            </tr><tr>
              <td scope="row"><code class="literal">ssl-cipher=<em class="replaceable"><code>cipher_list</code></em></code></td>
              <td>Permissible SSL ciphers.</td>
            </tr><tr>
              <td scope="row"><code class="literal">ssl-key=<em class="replaceable"><code>file_name</code></em></code></td>
              <td>Key file.</td>
            </tr><tr>
              <td scope="row"><code class="literal">timeout=<em class="replaceable"><code>seconds</code></em></code></td>
              <td>Like <code class="literal">connect-timeout</code>.</td>
            </tr><tr>
              <td scope="row"><code class="literal">user</code></td>
              <td>Default user.</td>
</tr></tbody></table>
</div>
<p>
          <code class="literal">timeout</code> has been replaced by
          <code class="literal">connect-timeout</code>, but
          <code class="literal">timeout</code> is still supported for backward
          compatibility.
        </p><p>
          For more information about option files used by MySQL
          programs, see <a class="xref" href="programs.html#option-files" title="4.2.6 Using Option Files">Section 4.2.6, “Using Option Files”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-options-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if you specify an unknown option.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-options-example"></a>Example</h5>

</div>

</div>

</div>
<p>
          The following <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a>
          calls request the use of compression in the client/server
          protocol, cause options to be read from the
          <code class="literal">[odbc]</code> group in option files, and disable
          transaction autocommit mode:
        </p><pre data-lang="c" class="programlisting">
MYSQL mysql;

mysql_init(&amp;mysql);
mysql_options(&amp;mysql,MYSQL_OPT_COMPRESS,0);
mysql_options(&amp;mysql,MYSQL_READ_DEFAULT_GROUP,"odbc");
mysql_options(&amp;mysql,MYSQL_INIT_COMMAND,"SET autocommit=0");
if (!mysql_real_connect(&amp;mysql,"host","user","passwd","database",0,NULL,0))
{
    fprintf(stderr, "Failed to connect to database: Error: %s\n",
          mysql_error(&amp;mysql));
}
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-options4"></a>27.8.7.51 mysql_options4()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710573918976"></a><p>
        <code class="literal">int mysql_options4(MYSQL *mysql, enum mysql_option
        option, const void *arg1, const void *arg2)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-options4-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          <a class="link" href="connectors-apis.html#mysql-options4" title="27.8.7.51 mysql_options4()"><code class="literal">mysql_options4()</code></a> is similar to
          <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> but has an
          extra fourth argument so that two values can be passed for the
          option specified in the second argument.
        </p><p>
          The following list describes the permitted options, their
          effect, and how <code class="literal">arg1</code> and
          <code class="literal">arg2</code> are used.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <code class="literal">MYSQL_OPT_CONNECT_ATTR_ADD</code> (argument
              types: <code class="literal">char *, char *</code>)
            </p><p>
              This option adds an attribute key/value pair to the
              current set of connection attributes to pass to the server
              at connect time. Both arguments are pointers to
              null-terminated strings. The first and second strings
              indicate the key and value, respectively. If the key is
              empty or already exists in the current set of connection
              attributes, an error occurs. Comparison of the key name
              with existing keys is case-sensitive.
            </p><p>
              Key names that begin with an underscore
              (<code class="literal">_</code>) are reserved for internal use and
              should not be created by application programs. This
              convention permits new attributes to be introduced by
              MySQL without colliding with application attributes.
            </p><p>
              <a class="link" href="connectors-apis.html#mysql-options4" title="27.8.7.51 mysql_options4()"><code class="literal">mysql_options4()</code></a> imposes a
              limit of 64KB on the aggregate size of connection
              attribute data it will accept. For calls that cause this
              limit to be exceeded, a
              <a class="link" href="error-handling.html#error_cr_invalid_parameter_no"><code class="literal">CR_INVALID_PARAMETER_NO</code></a>
              error occurs. Attribute size-limit checks also occur on
              the server side. For details, see
              <a class="xref" href="performance-schema.html#performance-schema-connection-attribute-tables" title="25.11.9 Performance Schema Connection Attribute Tables">Section 25.11.9, “Performance Schema Connection Attribute Tables”</a>,
              which also describes how the Performance Schema exposes
              connection attributes through the
              <a class="link" href="performance-schema.html#session-connect-attrs-table" title="25.11.9.2 The session_connect_attrs Table"><code class="literal">session_connect_attrs</code></a> and
              <a class="link" href="performance-schema.html#session-account-connect-attrs-table" title="25.11.9.1 The session_account_connect_attrs Table"><code class="literal">session_account_connect_attrs</code></a>
              tables.
            </p><p>
              See also the descriptions for the
              <code class="literal">MYSQL_OPT_CONNECT_ATTR_RESET</code>
              <code class="literal">MYSQL_OPT_CONNECT_ATTR_DELETE</code> options
              in the description of the
              <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> function.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-options4-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if you specify an unknown option.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-options4-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_duplicate_connection_attr"><code class="literal">CR_DUPLICATE_CONNECTION_ATTR</code></a>
            </p><p>
              A duplicate attribute name was specified.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_invalid_parameter_no"><code class="literal">CR_INVALID_PARAMETER_NO</code></a>
            </p><p>
              A key name was empty or the amount of key/value connection
              attribute data exceeds 64KB limit.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_out_of_memory"><code class="literal">CR_OUT_OF_MEMORY</code></a>
            </p><p>
              Out of memory.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-options4-example"></a>Example</h5>

</div>

</div>

</div>
<p>
          This example demonstrates the calls that specify connection
          attributes:
        </p><pre data-lang="c" class="programlisting">
MYSQL mysql;

mysql_init(&amp;mysql);
mysql_options(&amp;mysql,MYSQL_OPT_CONNECT_ATTR_RESET, 0);
mysql_options4(&amp;mysql,MYSQL_OPT_CONNECT_ATTR_ADD, "key1", "value1");
mysql_options4(&amp;mysql,MYSQL_OPT_CONNECT_ATTR_ADD, "key2", "value2");
mysql_options4(&amp;mysql,MYSQL_OPT_CONNECT_ATTR_ADD, "key3", "value3");
mysql_options(&amp;mysql,MYSQL_OPT_CONNECT_ATTR_DELETE, "key1");
if (!mysql_real_connect(&amp;mysql,"host","user","passwd","database",0,NULL,0))
{
    fprintf(stderr, "Failed to connect to database: Error: %s\n",
        mysql_error(&amp;mysql));
}
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-ping"></a>27.8.7.52 mysql_ping()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710573879888"></a><p>
        <code class="literal">int mysql_ping(MYSQL *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-ping-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Checks whether the connection to the server is working. If the
          connection has gone down and auto-reconnect is enabled an
          attempt to reconnect is made. If the connection is down and
          auto-reconnect is disabled,
          <a class="link" href="connectors-apis.html#mysql-ping" title="27.8.7.52 mysql_ping()"><code class="literal">mysql_ping()</code></a> returns an error.
        </p><p>
          Auto-reconnect is disabled by default. To enable it, call
          <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> with the
          <code class="literal">MYSQL_OPT_RECONNECT</code> option. For details,
          see <a class="xref" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()">Section 27.8.7.50, “mysql_options()”</a>.
        </p><p>
          <a class="link" href="connectors-apis.html#mysql-ping" title="27.8.7.52 mysql_ping()"><code class="literal">mysql_ping()</code></a> can be used by
          clients that remain idle for a long while, to check whether
          the server has closed the connection and reconnect if
          necessary.
        </p><p>
          If <a class="link" href="connectors-apis.html#mysql-ping" title="27.8.7.52 mysql_ping()"><code class="literal">mysql_ping()</code></a>) does cause a
          reconnect, there is no explicit indication of it. To determine
          whether a reconnect occurs, call
          <a class="link" href="connectors-apis.html#mysql-thread-id" title="27.8.7.76 mysql_thread_id()"><code class="literal">mysql_thread_id()</code></a> to get the
          original connection identifier before calling
          <a class="link" href="connectors-apis.html#mysql-ping" title="27.8.7.52 mysql_ping()"><code class="literal">mysql_ping()</code></a>, then call
          <a class="link" href="connectors-apis.html#mysql-thread-id" title="27.8.7.76 mysql_thread_id()"><code class="literal">mysql_thread_id()</code></a> again to see
          whether the identifier has changed.
        </p><p>
          If reconnect occurs, some characteristics of the connection
          will have been reset. For details about these characteristics,
          see <a class="xref" href="connectors-apis.html#c-api-auto-reconnect" title="27.8.20 C API Automatic Reconnection Control">Section 27.8.20, “C API Automatic Reconnection Control”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-ping-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero if the connection to the server is active. Nonzero if an
          error occurred. A nonzero return does not indicate whether the
          MySQL server itself is down; the connection might be broken
          for other reasons such as network problems.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-ping-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-query"></a>27.8.7.53 mysql_query()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710573850848"></a><p>
        <code class="literal">int mysql_query(MYSQL *mysql, const char
        *stmt_str)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-query-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Executes the SQL statement pointed to by the null-terminated
          string <code class="literal">stmt_str</code>. Normally, the string must
          consist of a single SQL statement without a terminating
          semicolon (<code class="literal">;</code>) or <code class="literal">\g</code>. If
          multiple-statement execution has been enabled, the string can
          contain several statements separated by semicolons. See
          <a class="xref" href="connectors-apis.html#c-api-multiple-queries" title="27.8.16 C API Multiple Statement Execution Support">Section 27.8.16, “C API Multiple Statement Execution Support”</a>.
        </p><p>
          <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a> cannot be used
          for statements that contain binary data; you must use
          <a class="link" href="connectors-apis.html#mysql-real-query" title="27.8.7.57 mysql_real_query()"><code class="literal">mysql_real_query()</code></a> instead.
          (Binary data may contain the <code class="literal">\0</code> character,
          which <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a> interprets
          as the end of the statement string.)
        </p><p>
          If you want to know whether the statement returns a result
          set, you can use
          <a class="link" href="connectors-apis.html#mysql-field-count" title="27.8.7.22 mysql_field_count()"><code class="literal">mysql_field_count()</code></a> to check
          for this. See <a class="xref" href="connectors-apis.html#mysql-field-count" title="27.8.7.22 mysql_field_count()">Section 27.8.7.22, “mysql_field_count()”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-query-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-query-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-real-connect"></a>27.8.7.54 mysql_real_connect()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710573822208"></a><p>
        <code class="literal">MYSQL *mysql_real_connect(MYSQL *mysql, const char
        *host, const char *user, const char *passwd, const char *db,
        unsigned int port, const char *unix_socket, unsigned long
        client_flag)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-real-connect-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a> attempts
          to establish a connection to a MySQL database engine running
          on <code class="literal">host</code>.
          <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a> must
          complete successfully before you can execute any other API
          functions that require a valid <code class="literal">MYSQL</code>
          connection handler structure.
        </p><p>
          The parameters are specified as follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              For the first parameter, specify the address of an
              existing <code class="literal">MYSQL</code> structure. Before
              calling
              <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a>, call
              <a class="link" href="connectors-apis.html#mysql-init" title="27.8.7.37 mysql_init()"><code class="literal">mysql_init()</code></a> to initialize
              the <code class="literal">MYSQL</code> structure. You can change a
              lot of connect options with the
              <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> call. See
              <a class="xref" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()">Section 27.8.7.50, “mysql_options()”</a>.
            </p></li><li class="listitem"><p>
              The value of <code class="literal">host</code> may be either a host
              name or an IP address. If <code class="literal">host</code> is
              <code class="literal">NULL</code> or the string
              <code class="literal">"localhost"</code>, a connection to the local
              host is assumed. For Windows, the client connects using a
              shared-memory connection, if the server has shared-memory
              connections enabled. Otherwise, TCP/IP is used. For Unix,
              the client connects using a Unix socket file. For local
              connections, you can also influence the type of connection
              to use with the <code class="literal">MYSQL_OPT_PROTOCOL</code> or
              <code class="literal">MYSQL_OPT_NAMED_PIPE</code> options to
              <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a>. The type
              of connection must be supported by the server. For a
              <code class="literal">host</code> value of <code class="literal">"."</code> on
              Windows, the client connects using a named pipe, if the
              server has named-pipe connections enabled. If named-pipe
              connections are not enabled, an error occurs.
            </p></li><li class="listitem"><p>
              The <code class="literal">user</code> parameter contains the user's
              MySQL login ID. If <code class="literal">user</code> is
              <code class="literal">NULL</code> or the empty string
              <code class="literal">""</code>, the current user is assumed. Under
              Unix, this is the current login name. Under Windows ODBC,
              the current user name must be specified explicitly. See
              the Connector/ODBC section of
              <a class="xref" href="connectors-apis.html" title="Chapter 27 Connectors and APIs">Chapter 27, <i>Connectors and APIs</i></a>.
            </p></li><li class="listitem"><p>
              The <code class="literal">passwd</code> parameter contains the
              password for <code class="literal">user</code>. If
              <code class="literal">passwd</code> is <code class="literal">NULL</code>, only
              entries in the <code class="literal">user</code> table for the user
              that have a blank (empty) password field are checked for a
              match. This enables the database administrator to set up
              the MySQL privilege system in such a way that users get
              different privileges depending on whether they have
              specified a password.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
                Do not attempt to encrypt the password before calling
                <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a>;
                password encryption is handled automatically by the
                client API.
</p>
</div>
</li><li class="listitem"><p>
              The <code class="literal">user</code> and <code class="literal">passwd</code>
              parameters use whatever character set has been configured
              for the <code class="literal">MYSQL</code> object. By default, this
              is <code class="literal">latin1</code>, but can be changed by
              calling <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options(mysql,
              MYSQL_SET_CHARSET_NAME,
              "<em class="replaceable"><code>charset_name</code></em>")</code></a> prior
              to connecting.
            </p></li><li class="listitem"><p>
              <code class="literal">db</code> is the database name. If
              <code class="literal">db</code> is not <code class="literal">NULL</code>, the
              connection sets the default database to this value.
            </p></li><li class="listitem"><p>
              If <code class="literal">port</code> is not 0, the value is used as
              the port number for the TCP/IP connection. Note that the
              <code class="literal">host</code> parameter determines the type of
              the connection.
            </p></li><li class="listitem"><p>
              If <code class="literal">unix_socket</code> is not
              <code class="literal">NULL</code>, the string specifies the socket
              or named pipe to use. Note that the
              <code class="literal">host</code> parameter determines the type of
              the connection.
            </p></li><li class="listitem"><p>
              The value of <code class="literal">client_flag</code> is usually 0,
              but can be set to a combination of the following flags to
              enable certain features:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                  <code class="literal">CAN_HANDLE_EXPIRED_PASSWORDS</code>: The
                  client can handle expired passwords. For more
                  information, see
                  <a class="xref" href="security.html#expired-password-handling" title="6.3.8 Password Expiration and Sandbox Mode">Section 6.3.8, “Password Expiration and Sandbox Mode”</a>.
                </p></li><li class="listitem"><p>
                  <code class="literal">CLIENT_COMPRESS</code>: Use compression in
                  the client/server protocol.
                </p></li><li class="listitem"><p>
                  <code class="literal">CLIENT_FOUND_ROWS</code>: Return the
                  number of found (matched) rows, not the number of
                  changed rows.
                </p></li><li class="listitem"><p>
                  <code class="literal">CLIENT_IGNORE_SIGPIPE</code>: Prevents the
                  client library from installing a
                  <code class="literal">SIGPIPE</code> signal handler. This can be
                  used to avoid conflicts with a handler that the
                  application has already installed.
                </p></li><li class="listitem"><p>
                  <code class="literal">CLIENT_IGNORE_SPACE</code>: Permit spaces
                  after function names. Makes all functions names
                  reserved words.
                </p></li><li class="listitem"><p>
                  <code class="literal">CLIENT_INTERACTIVE</code>: Permit
                  <a class="link" href="server-administration.html#sysvar_interactive_timeout"><code class="literal">interactive_timeout</code></a>
                  seconds of inactivity (rather than
                  <a class="link" href="server-administration.html#sysvar_wait_timeout"><code class="literal">wait_timeout</code></a> seconds)
                  before closing the connection. The client's session
                  <a class="link" href="server-administration.html#sysvar_wait_timeout"><code class="literal">wait_timeout</code></a> variable
                  is set to the value of the session
                  <a class="link" href="server-administration.html#sysvar_interactive_timeout"><code class="literal">interactive_timeout</code></a>
                  variable.
                </p></li><li class="listitem"><p>
                  <code class="literal">CLIENT_LOCAL_FILES</code>: Enable
                  <a class="link" href="sql-syntax.html#load-data" title="13.2.6 LOAD DATA INFILE Syntax"><code class="literal">LOAD DATA
                  LOCAL</code></a> handling.
                </p></li><li class="listitem"><p>
                  <code class="literal">CLIENT_MULTI_RESULTS</code>: Tell the
                  server that the client can handle multiple result sets
                  from multiple-statement executions or stored
                  procedures. This flag is automatically enabled if
                  <code class="literal">CLIENT_MULTI_STATEMENTS</code> is enabled.
                  See the note following this table for more information
                  about this flag.
                </p></li><li class="listitem"><p>
                  <code class="literal">CLIENT_MULTI_STATEMENTS</code>: Tell the
                  server that the client may send multiple statements in
                  a single string (separated by <code class="literal">;</code>
                  characters). If this flag is not set,
                  multiple-statement execution is disabled. See the note
                  following this table for more information about this
                  flag.
                </p></li><li class="listitem"><p>
                  <code class="literal">CLIENT_NO_SCHEMA</code> Do not permit
                  <em class="replaceable"><code>db_name.tbl_name.col_name</code></em>
                  syntax. This is for ODBC. It causes the parser to
                  generate an error if you use that syntax, which is
                  useful for trapping bugs in some ODBC programs.
                </p></li><li class="listitem"><p>
                  <code class="literal">CLIENT_ODBC</code>: Unused.
                </p></li><li class="listitem"><p>
                  <code class="literal">CLIENT_SSL</code>: Use SSL (encrypted
                  protocol). Do not set this option within an
                  application program; it is set internally in the
                  client library. Instead, use
                  <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> or
                  <a class="link" href="connectors-apis.html#mysql-ssl-set" title="27.8.7.73 mysql_ssl_set()"><code class="literal">mysql_ssl_set()</code></a> before
                  calling
                  <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a>.
                </p></li><li class="listitem"><p>
                  <code class="literal">CLIENT_REMEMBER_OPTIONS</code> Remember
                  options specified by calls to
                  <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a>.
                  Without this option, if
                  <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a>
                  fails, you must repeat the
                  <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> calls
                  before trying to connect again. With this option, the
                  <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> calls
                  need not be repeated.
</p></li></ul>
</div>
</li></ul>
</div>
<p>
          If your program uses <a class="link" href="sql-syntax.html#call" title="13.2.1 CALL Syntax"><code class="literal">CALL</code></a>
          statements to execute stored procedures, the
          <code class="literal">CLIENT_MULTI_RESULTS</code> flag must be enabled.
          This is because each <a class="link" href="sql-syntax.html#call" title="13.2.1 CALL Syntax"><code class="literal">CALL</code></a>
          returns a result to indicate the call status, in addition to
          any result sets that might be returned by statements executed
          within the procedure. Because
          <a class="link" href="sql-syntax.html#call" title="13.2.1 CALL Syntax"><code class="literal">CALL</code></a> can return multiple
          results, process them using a loop that calls
          <a class="link" href="connectors-apis.html#mysql-next-result" title="27.8.7.47 mysql_next_result()"><code class="literal">mysql_next_result()</code></a> to
          determine whether there are more results.
        </p><p>
          <code class="literal">CLIENT_MULTI_RESULTS</code> can be enabled when
          you call <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a>,
          either explicitly by passing the
          <code class="literal">CLIENT_MULTI_RESULTS</code> flag itself, or
          implicitly by passing
          <code class="literal">CLIENT_MULTI_STATEMENTS</code> (which also enables
          <code class="literal">CLIENT_MULTI_RESULTS</code>). In MySQL
          5.7, <code class="literal">CLIENT_MULTI_RESULTS</code> is
          enabled by default.
        </p><p>
          If you enable <code class="literal">CLIENT_MULTI_STATEMENTS</code> or
          <code class="literal">CLIENT_MULTI_RESULTS</code>, process the result
          for every call to
          <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a> or
          <a class="link" href="connectors-apis.html#mysql-real-query" title="27.8.7.57 mysql_real_query()"><code class="literal">mysql_real_query()</code></a> by using a
          loop that calls
          <a class="link" href="connectors-apis.html#mysql-next-result" title="27.8.7.47 mysql_next_result()"><code class="literal">mysql_next_result()</code></a> to
          determine whether there are more results. For an example, see
          <a class="xref" href="connectors-apis.html#c-api-multiple-queries" title="27.8.16 C API Multiple Statement Execution Support">Section 27.8.16, “C API Multiple Statement Execution Support”</a>.
        </p><p>
          For some parameters, it is possible to have the value taken
          from an option file rather than from an explicit value in the
          <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a> call. To
          do this, call <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a>
          with the <code class="literal">MYSQL_READ_DEFAULT_FILE</code> or
          <code class="literal">MYSQL_READ_DEFAULT_GROUP</code> option before
          calling <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a>.
          Then, in the
          <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a> call,
          specify the <span class="quote">“<span class="quote">no-value</span>”</span> value for each parameter
          to be read from an option file:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              For <code class="literal">host</code>, specify a value of
              <code class="literal">NULL</code> or the empty string
              (<code class="literal">""</code>).
            </p></li><li class="listitem"><p>
              For <code class="literal">user</code>, specify a value of
              <code class="literal">NULL</code> or the empty string.
            </p></li><li class="listitem"><p>
              For <code class="literal">passwd</code>, specify a value of
              <code class="literal">NULL</code>. (For the password, a value of the
              empty string in the
              <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a> call
              cannot be overridden in an option file, because the empty
              string indicates explicitly that the MySQL account must
              have an empty password.)
            </p></li><li class="listitem"><p>
              For <code class="literal">db</code>, specify a value of
              <code class="literal">NULL</code> or the empty string.
            </p></li><li class="listitem"><p>
              For <code class="literal">port</code>, specify a value of 0.
            </p></li><li class="listitem"><p>
              For <code class="literal">unix_socket</code>, specify a value of
              <code class="literal">NULL</code>.
</p></li></ul>
</div>
<p>
          If no value is found in an option file for a parameter, its
          default value is used as indicated in the descriptions given
          earlier in this section.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-real-connect-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          A <code class="literal">MYSQL*</code> connection handler if the
          connection was successful, <code class="literal">NULL</code> if the
          connection was unsuccessful. For a successful connection, the
          return value is the same as the value of the first parameter.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-real-connect-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_conn_host_error"><code class="literal">CR_CONN_HOST_ERROR</code></a>
            </p><p>
              Failed to connect to the MySQL server.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_connection_error"><code class="literal">CR_CONNECTION_ERROR</code></a>
            </p><p>
              Failed to connect to the local MySQL server.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_ipsock_error"><code class="literal">CR_IPSOCK_ERROR</code></a>
            </p><p>
              Failed to create an IP socket.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_out_of_memory"><code class="literal">CR_OUT_OF_MEMORY</code></a>
            </p><p>
              Out of memory.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_socket_create_error"><code class="literal">CR_SOCKET_CREATE_ERROR</code></a>
            </p><p>
              Failed to create a Unix socket.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_host"><code class="literal">CR_UNKNOWN_HOST</code></a>
            </p><p>
              Failed to find the IP address for the host name.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_version_error"><code class="literal">CR_VERSION_ERROR</code></a>
            </p><p>
              A protocol mismatch resulted from attempting to connect to
              a server with a client library that uses a different
              protocol version.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_namedpipeopen_error"><code class="literal">CR_NAMEDPIPEOPEN_ERROR</code></a>
            </p><p>
              Failed to create a named pipe on Windows.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_namedpipewait_error"><code class="literal">CR_NAMEDPIPEWAIT_ERROR</code></a>
            </p><p>
              Failed to wait for a named pipe on Windows.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_namedpipesetstate_error"><code class="literal">CR_NAMEDPIPESETSTATE_ERROR</code></a>
            </p><p>
              Failed to get a pipe handler on Windows.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              If <a class="link" href="server-administration.html#sysvar_connect_timeout"><code class="literal">connect_timeout</code></a> &gt; 0
              and it took longer than
              <a class="link" href="server-administration.html#sysvar_connect_timeout"><code class="literal">connect_timeout</code></a> seconds
              to connect to the server or if the server died while
              executing the <code class="literal">init-command</code>.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_already_connected"><code class="literal">CR_ALREADY_CONNECTED</code></a>
            </p><p>
              The <code class="literal">MYSQL</code> connection handler is already
              connected.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-real-connect-example"></a>Example</h5>

</div>

</div>

</div>
<pre data-lang="c" class="programlisting">
MYSQL mysql;

mysql_init(&amp;mysql);
mysql_options(&amp;mysql,MYSQL_READ_DEFAULT_GROUP,"your_prog_name");
if (!mysql_real_connect(&amp;mysql,"host","user","passwd","database",0,NULL,0))
{
    fprintf(stderr, "Failed to connect to database: Error: %s\n",
          mysql_error(&amp;mysql));
}
</pre><p>
          By using <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> the
          MySQL client library reads the <code class="literal">[client]</code> and
          <code class="literal">[your_prog_name]</code> sections in the
          <code class="filename">my.cnf</code> file which ensures that your
          program works, even if someone has set up MySQL in some
          nonstandard way.
        </p><p>
          Upon connection,
          <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a> sets the
          <code class="literal">reconnect</code> flag (part of the
          <code class="literal">MYSQL</code> structure) to a value of
          <code class="literal">1</code> in versions of the API older than 5.0.3,
          or <code class="literal">0</code> in newer versions. A value of
          <code class="literal">1</code> for this flag indicates that if a
          statement cannot be performed because of a lost connection, to
          try reconnecting to the server before giving up. You can use
          the <code class="literal">MYSQL_OPT_RECONNECT</code> option to
          <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> to control
          reconnection behavior.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-real-escape-string"></a>27.8.7.55 mysql_real_escape_string()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710573632768"></a><p>
        <code class="literal">unsigned long mysql_real_escape_string(MYSQL *mysql,
        char *to, const char *from, unsigned long length)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-real-escape-string-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          This function creates a legal SQL string for use in an SQL
          statement. See <a class="xref" href="language-structure.html#string-literals" title="9.1.1 String Literals">Section 9.1.1, “String Literals”</a>.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
            <a class="link" href="connectors-apis.html#mysql-real-escape-string" title="27.8.7.55 mysql_real_escape_string()"><code class="literal">mysql_real_escape_string()</code></a>
            fails and produces an
            <a class="link" href="error-handling.html#error_cr_insecure_api_err"><code class="literal">CR_INSECURE_API_ERR</code></a> error if
            the <a class="link" href="server-administration.html#sqlmode_no_backslash_escapes"><code class="literal">NO_BACKSLASH_ESCAPES</code></a>
            SQL mode is enabled. In this case, the function cannot
            escape quote characters except by doubling them, and to do
            this properly, it must know more information about the
            quoting context than is available. Instead, use
            <a class="link" href="connectors-apis.html#mysql-real-escape-string-quote" title="27.8.7.56 mysql_real_escape_string_quote()"><code class="literal">mysql_real_escape_string_quote()</code></a>,
            which takes an extra argument for specifying the quoting
            context.
</p>
</div>
<p>
          The <code class="literal">mysql</code> argument must be a valid, open
          connection because character escaping depends on the character
          set in use by the server.
        </p><a class="indexterm" name="idm140710573620480"></a><p>
          The string in the <code class="literal">from</code> argument is encoded
          to produce an escaped SQL string, taking into account the
          current character set of the connection. The result is placed
          in the <code class="literal">to</code> argument, followed by a
          terminating null byte.
        </p><p>
          Characters encoded are <code class="literal">\</code>,
          <code class="literal">'</code>, <code class="literal">"</code>,
          <code class="literal">NUL</code> (ASCII 0), <code class="literal">\n</code>,
          <code class="literal">\r</code>, and Control+Z. Strictly speaking, MySQL
          requires only that backslash and the quote character used to
          quote the string in the query be escaped.
          <a class="link" href="connectors-apis.html#mysql-real-escape-string" title="27.8.7.55 mysql_real_escape_string()"><code class="literal">mysql_real_escape_string()</code></a>
          quotes the other characters to make them easier to read in log
          files. For comparison, see the quoting rules for literal
          strings and the <a class="link" href="functions.html#function_quote"><code class="literal">QUOTE()</code></a> SQL
          function in <a class="xref" href="language-structure.html#string-literals" title="9.1.1 String Literals">Section 9.1.1, “String Literals”</a>, and
          <a class="xref" href="functions.html#string-functions" title="12.5 String Functions">Section 12.5, “String Functions”</a>.
        </p><p>
          The string pointed to by <code class="literal">from</code> must be
          <code class="literal">length</code> bytes long. You must allocate the
          <code class="literal">to</code> buffer to be at least
          <code class="literal">length*2+1</code> bytes long. (In the worst case,
          each character may need to be encoded as using two bytes, and
          there must be room for the terminating null byte.) When
          <a class="link" href="connectors-apis.html#mysql-real-escape-string" title="27.8.7.55 mysql_real_escape_string()"><code class="literal">mysql_real_escape_string()</code></a>
          returns, the contents of <code class="literal">to</code> is a
          null-terminated string. The return value is the length of the
          encoded string, not including the terminating null byte.
        </p><p>
          If you must change the character set of the connection, use
          the <a class="link" href="connectors-apis.html#mysql-set-character-set" title="27.8.7.67 mysql_set_character_set()"><code class="literal">mysql_set_character_set()</code></a>
          function rather than executing a <a class="link" href="sql-syntax.html#set-names" title="13.7.4.3 SET NAMES Syntax"><code class="literal">SET
          NAMES</code></a> (or <a class="link" href="sql-syntax.html#set-character-set" title="13.7.4.2 SET CHARACTER SET Syntax"><code class="literal">SET CHARACTER
          SET</code></a>) statement.
          <a class="link" href="connectors-apis.html#mysql-set-character-set" title="27.8.7.67 mysql_set_character_set()"><code class="literal">mysql_set_character_set()</code></a>
          works like <a class="link" href="sql-syntax.html#set-names" title="13.7.4.3 SET NAMES Syntax"><code class="literal">SET NAMES</code></a> but also
          affects the character set used by
          <a class="link" href="connectors-apis.html#mysql-real-escape-string" title="27.8.7.55 mysql_real_escape_string()"><code class="literal">mysql_real_escape_string()</code></a>,
          which <a class="link" href="sql-syntax.html#set-names" title="13.7.4.3 SET NAMES Syntax"><code class="literal">SET NAMES</code></a> does not.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-real-escape-string-example"></a>Example</h5>

</div>

</div>

</div>
<p>
          The following example inserts two escaped strings into an
          <code class="literal">INSERT</code> statement, each within single quote
          characters:
        </p><pre data-lang="c" class="programlisting">
char query[1000],*end;

end = my_stpcpy(query,"INSERT INTO test_table VALUES('");
end += mysql_real_escape_string(&amp;mysql,end,"What is this",12);
end = my_stpcpy(end,"','");
end += mysql_real_escape_string(&amp;mysql,end,"binary data: \0\r\n",16);
end = my_stpcpy(end,"')");

if (mysql_real_query(&amp;mysql,query,(unsigned int) (end - query)))
{
   fprintf(stderr, "Failed to insert row, Error: %s\n",
           mysql_error(&amp;mysql));
}
</pre><p>
          The <code class="literal">my_stpcpy()</code> function used in the
          example is included in the <code class="literal">libmysqlclient</code>
          library and works like <code class="literal">strcpy()</code> but returns
          a pointer to the terminating null of the first parameter.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-real-escape-string-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          The length of the encoded string that is placed into the
          <code class="literal">to</code> argument, not including the terminating
          null byte, or -1 if an error occurs.
        </p><p>
          Because
          <a class="link" href="connectors-apis.html#mysql-real-escape-string" title="27.8.7.55 mysql_real_escape_string()"><code class="literal">mysql_real_escape_string()</code></a>
          returns an unsigned value, you can check for -1 by comparing
          the return value to <code class="literal">(unsigned long)-1</code> (or
          to <code class="literal">(unsigned long)~0</code>, which is equivalent).
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-real-escape-string-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_insecure_api_err"><code class="literal">CR_INSECURE_API_ERR</code></a>
            </p><p>
              This error occurs if the
              <a class="link" href="server-administration.html#sqlmode_no_backslash_escapes"><code class="literal">NO_BACKSLASH_ESCAPES</code></a> SQL
              mode is enabled because, in that case,
              <a class="link" href="connectors-apis.html#mysql-real-escape-string" title="27.8.7.55 mysql_real_escape_string()"><code class="literal">mysql_real_escape_string()</code></a>
              cannot be guaranteed to produce a properly encoded result.
              To avoid this error, use
              <a class="link" href="connectors-apis.html#mysql-real-escape-string-quote" title="27.8.7.56 mysql_real_escape_string_quote()"><code class="literal">mysql_real_escape_string_quote()</code></a>
              instead.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-real-escape-string-quote"></a>27.8.7.56 mysql_real_escape_string_quote()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710573571680"></a><p>
        <code class="literal">unsigned long mysql_real_escape_string_quote(MYSQL
        *mysql, char *to, const char *from, unsigned long length, char
        quote)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-real-escape-string-quote-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          This function creates a legal SQL string for use in an SQL
          statement. See <a class="xref" href="language-structure.html#string-literals" title="9.1.1 String Literals">Section 9.1.1, “String Literals”</a>.
        </p><p>
          The <code class="literal">mysql</code> argument must be a valid, open
          connection because character escaping depends on the character
          set in use by the server.
        </p><a class="indexterm" name="idm140710573565744"></a><p>
          The string in the <code class="literal">from</code> argument is encoded
          to produce an escaped SQL string, taking into account the
          current character set of the connection. The result is placed
          in the <code class="literal">to</code> argument, followed by a
          terminating null byte.
        </p><p>
          Characters encoded are <code class="literal">\</code>,
          <code class="literal">'</code>, <code class="literal">"</code>,
          <code class="literal">NUL</code> (ASCII 0), <code class="literal">\n</code>,
          <code class="literal">\r</code>, Control+Z, and <code class="literal">`</code>.
          Strictly speaking, MySQL requires only that backslash and the
          quote character used to quote the string in the query be
          escaped.
          <a class="link" href="connectors-apis.html#mysql-real-escape-string-quote" title="27.8.7.56 mysql_real_escape_string_quote()"><code class="literal">mysql_real_escape_string_quote()</code></a>
          quotes the other characters to make them easier to read in log
          files. For comparison, see the quoting rules for literal
          strings and the <a class="link" href="functions.html#function_quote"><code class="literal">QUOTE()</code></a> SQL
          function in <a class="xref" href="language-structure.html#string-literals" title="9.1.1 String Literals">Section 9.1.1, “String Literals”</a>, and
          <a class="xref" href="functions.html#string-functions" title="12.5 String Functions">Section 12.5, “String Functions”</a>.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
            If the <a class="link" href="server-administration.html#sqlmode_ansi_quotes"><code class="literal">ANSI_QUOTES</code></a> SQL
            mode is enabled,
            <a class="link" href="connectors-apis.html#mysql-real-escape-string-quote" title="27.8.7.56 mysql_real_escape_string_quote()"><code class="literal">mysql_real_escape_string_quote()</code></a>
            cannot be used to escape double quote characters for use
            within double-quoted identifiers. (The function cannot tell
            whether the mode is enabled to determine the proper escaping
            character.)
</p>
</div>
<p>
          The string pointed to by <code class="literal">from</code> must be
          <code class="literal">length</code> bytes long. You must allocate the
          <code class="literal">to</code> buffer to be at least
          <code class="literal">length*2+1</code> bytes long. (In the worst case,
          each character may need to be encoded as using two bytes, and
          there must be room for the terminating null byte.) When
          <a class="link" href="connectors-apis.html#mysql-real-escape-string-quote" title="27.8.7.56 mysql_real_escape_string_quote()"><code class="literal">mysql_real_escape_string_quote()</code></a>
          returns, the contents of <code class="literal">to</code> is a
          null-terminated string. The return value is the length of the
          encoded string, not including the terminating null byte.
        </p><p>
          The <code class="literal">quote</code> argument indicates the context in
          which the escaped string is to be placed. Suppose that you
          intend to escape the <code class="literal">from</code> argument and
          insert the escaped string (designated here by
          <em class="replaceable"><code>str</code></em>) into one of the following
          statements:
        </p><pre data-lang="sql" class="programlisting">
1) SELECT * FROM table WHERE name = '<em class="replaceable"><code>str</code></em>'
2) SELECT * FROM table WHERE name = "<em class="replaceable"><code>str</code></em>"
3) SELECT * FROM `<em class="replaceable"><code>str</code></em>` WHERE id = 103
</pre><p>
          To perform escaping properly for each statement, call
          <a class="link" href="connectors-apis.html#mysql-real-escape-string-quote" title="27.8.7.56 mysql_real_escape_string_quote()"><code class="literal">mysql_real_escape_string_quote()</code></a>
          as follows, where the final argument indicates the quoting
          context:
        </p><pre data-lang="c" class="programlisting">
1) len = mysql_real_escape_string_quote(&amp;mysql,to,from,from_len,'\'');
2) len = mysql_real_escape_string_quote(&amp;mysql,to,from,from_len,'"');
3) len = mysql_real_escape_string_quote(&amp;mysql,to,from,from_len,'`');
</pre><p>
          If you must change the character set of the connection, use
          the <a class="link" href="connectors-apis.html#mysql-set-character-set" title="27.8.7.67 mysql_set_character_set()"><code class="literal">mysql_set_character_set()</code></a>
          function rather than executing a <a class="link" href="sql-syntax.html#set-names" title="13.7.4.3 SET NAMES Syntax"><code class="literal">SET
          NAMES</code></a> (or <a class="link" href="sql-syntax.html#set-character-set" title="13.7.4.2 SET CHARACTER SET Syntax"><code class="literal">SET CHARACTER
          SET</code></a>) statement.
          <a class="link" href="connectors-apis.html#mysql-set-character-set" title="27.8.7.67 mysql_set_character_set()"><code class="literal">mysql_set_character_set()</code></a>
          works like <a class="link" href="sql-syntax.html#set-names" title="13.7.4.3 SET NAMES Syntax"><code class="literal">SET NAMES</code></a> but also
          affects the character set used by
          <a class="link" href="connectors-apis.html#mysql-real-escape-string-quote" title="27.8.7.56 mysql_real_escape_string_quote()"><code class="literal">mysql_real_escape_string_quote()</code></a>,
          which <a class="link" href="sql-syntax.html#set-names" title="13.7.4.3 SET NAMES Syntax"><code class="literal">SET NAMES</code></a> does not.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-real-escape-string-quote-example"></a>Example</h5>

</div>

</div>

</div>
<p>
          The following example inserts two escaped strings into an
          <code class="literal">INSERT</code> statement, each within single quote
          characters:
        </p><pre data-lang="c" class="programlisting">
char query[1000],*end;

end = my_stpcpy(query,"INSERT INTO test_table VALUES('");
end += mysql_real_escape_string_quote(&amp;mysql,end,"What is this",12,'\'');
end = my_stpcpy(end,"','");
end += mysql_real_escape_string_quote(&amp;mysql,end,"binary data: \0\r\n",16,'\'');
end = my_stpcpy(end,"')");

if (mysql_real_query(&amp;mysql,query,(unsigned int) (end - query)))
{
   fprintf(stderr, "Failed to insert row, Error: %s\n",
           mysql_error(&amp;mysql));
}
</pre><p>
          The <code class="literal">my_stpcpy()</code> function used in the
          example is included in the <code class="literal">libmysqlclient</code>
          library and works like <code class="literal">strcpy()</code> but returns
          a pointer to the terminating null of the first parameter.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-real-escape-string-quote-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          The length of the encoded string that is placed into the
          <code class="literal">to</code> argument, not including the terminating
          null byte.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-real-escape-string-quote-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-real-query"></a>27.8.7.57 mysql_real_query()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710573514720"></a><p>
        <code class="literal">int mysql_real_query(MYSQL *mysql, const char
        *stmt_str, unsigned long length)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-real-query-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Executes the SQL statement pointed to by
          <code class="literal">stmt_str</code>, a string
          <code class="literal">length</code> bytes long. Normally, the string
          must consist of a single SQL statement without a terminating
          semicolon (<code class="literal">;</code>) or <code class="literal">\g</code>. If
          multiple-statement execution has been enabled, the string can
          contain several statements separated by semicolons. See
          <a class="xref" href="connectors-apis.html#c-api-multiple-queries" title="27.8.16 C API Multiple Statement Execution Support">Section 27.8.16, “C API Multiple Statement Execution Support”</a>.
        </p><p>
          <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a> cannot be used
          for statements that contain binary data; you must use
          <a class="link" href="connectors-apis.html#mysql-real-query" title="27.8.7.57 mysql_real_query()"><code class="literal">mysql_real_query()</code></a> instead.
          (Binary data may contain the <code class="literal">\0</code> character,
          which <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a> interprets
          as the end of the statement string.) In addition,
          <a class="link" href="connectors-apis.html#mysql-real-query" title="27.8.7.57 mysql_real_query()"><code class="literal">mysql_real_query()</code></a> is faster
          than <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a> because it
          does not call <code class="literal">strlen()</code> on the statement
          string.
        </p><p>
          If you want to know whether the statement returns a result
          set, you can use
          <a class="link" href="connectors-apis.html#mysql-field-count" title="27.8.7.22 mysql_field_count()"><code class="literal">mysql_field_count()</code></a> to check
          for this. See <a class="xref" href="connectors-apis.html#mysql-field-count" title="27.8.7.22 mysql_field_count()">Section 27.8.7.22, “mysql_field_count()”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-real-query-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-real-query-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-refresh"></a>27.8.7.58 mysql_refresh()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710573482128"></a><p>
        <code class="literal">int mysql_refresh(MYSQL *mysql, unsigned int
        options)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-refresh-description"></a>Description</h5>

</div>

</div>

</div>

<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
            As of MySQL 5.7.11, <code class="literal">mysql_refresh()</code> is
            deprecated and will be removed in a future version of MySQL.
            Instead, use <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a>
            to execute a <a class="link" href="sql-syntax.html#flush" title="13.7.6.3 FLUSH Syntax"><code class="literal">FLUSH</code></a> statement.
</p>
</div>
<p>
          This function flushes tables or caches, or resets replication
          server information. The connected user must have the
          <a class="link" href="security.html#priv_reload"><code class="literal">RELOAD</code></a> privilege.
        </p><p>
          The <code class="literal">options</code> argument is a bitmask composed
          from any combination of the following values. Multiple values
          can be OR'ed together to perform multiple operations with a
          single call.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <code class="literal">REFRESH_GRANT</code>
            </p><p>
              Refresh the grant tables, like <a class="link" href="sql-syntax.html#flush-privileges"><code class="literal">FLUSH
              PRIVILEGES</code></a>.
            </p></li><li class="listitem"><p>
              <code class="literal">REFRESH_LOG</code>
            </p><p>
              Flush the logs, like <a class="link" href="sql-syntax.html#flush-logs"><code class="literal">FLUSH
              LOGS</code></a>.
            </p></li><li class="listitem"><p>
              <code class="literal">REFRESH_TABLES</code>
            </p><p>
              Flush the table cache, like <a class="link" href="sql-syntax.html#flush-tables"><code class="literal">FLUSH
              TABLES</code></a>.
            </p></li><li class="listitem"><p>
              <code class="literal">REFRESH_HOSTS</code>
            </p><p>
              Flush the host cache, like <a class="link" href="sql-syntax.html#flush-hosts"><code class="literal">FLUSH
              HOSTS</code></a>.
            </p></li><li class="listitem"><p>
              <code class="literal">REFRESH_STATUS</code>
            </p><p>
              Reset status variables, like <a class="link" href="sql-syntax.html#flush-status"><code class="literal">FLUSH
              STATUS</code></a>.
            </p></li><li class="listitem"><p>
              <code class="literal">REFRESH_THREADS</code>
            </p><p>
              Flush the thread cache.
            </p></li><li class="listitem"><p>
              <code class="literal">REFRESH_SLAVE</code>
            </p><p>
              On a slave replication server, reset the master server
              information and restart the slave, like
              <a class="link" href="sql-syntax.html#reset-slave" title="13.4.2.4 RESET SLAVE Syntax"><code class="literal">RESET SLAVE</code></a>.
            </p></li><li class="listitem"><p>
              <code class="literal">REFRESH_MASTER</code>
            </p><p>
              On a master replication server, remove the binary log
              files listed in the binary log index and truncate the
              index file, like <a class="link" href="sql-syntax.html#reset-master" title="13.4.1.2 RESET MASTER Syntax"><code class="literal">RESET
              MASTER</code></a>.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-refresh-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-refresh-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-reload"></a>27.8.7.59 mysql_reload()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710573432528"></a><p>
        <code class="literal">int mysql_reload(MYSQL *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-reload-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Asks the MySQL server to reload the grant tables. The
          connected user must have the
          <a class="link" href="security.html#priv_reload"><code class="literal">RELOAD</code></a> privilege.
        </p><p>
          This function is deprecated. Use
          <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a> to issue an SQL
          <a class="link" href="sql-syntax.html#flush-privileges"><code class="literal">FLUSH PRIVILEGES</code></a> statement
          instead.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-reload-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-reload-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-reset-connection"></a>27.8.7.60 mysql_reset_connection()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710573409376"></a><p>
        <code class="literal">int mysql_reset_connection(MYSQL *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-reset-connection-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Resets the connection to clear the session state.
        </p><p>
          <a class="link" href="connectors-apis.html#mysql-reset-connection" title="27.8.7.60 mysql_reset_connection()"><code class="literal">mysql_reset_connection()</code></a> has
          effects similar to
          <a class="link" href="connectors-apis.html#mysql-change-user" title="27.8.7.3 mysql_change_user()"><code class="literal">mysql_change_user()</code></a> or an
          auto-reconnect except that the connection is not closed and
          reopened, and reauthentication is not done. See
          <a class="xref" href="connectors-apis.html#mysql-change-user" title="27.8.7.3 mysql_change_user()">Section 27.8.7.3, “mysql_change_user()”</a>) and see
          <a class="xref" href="connectors-apis.html#c-api-auto-reconnect" title="27.8.20 C API Automatic Reconnection Control">Section 27.8.20, “C API Automatic Reconnection Control”</a>).
        </p><p>
          The connection-related state is affected as follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              Any active transactions are rolled back and autocommit
              mode is reset.
            </p></li><li class="listitem"><p>
              All table locks are released.
            </p></li><li class="listitem"><p>
              All <code class="literal">TEMPORARY</code> tables are closed (and
              dropped).
            </p></li><li class="listitem"><p>
              Session system variables are reinitialized to the values
              of the corresponding global system variables, including
              system variables that are set implicitly by statements
              such as <a class="link" href="sql-syntax.html#set-names" title="13.7.4.3 SET NAMES Syntax"><code class="literal">SET NAMES</code></a>.
            </p></li><li class="listitem"><p>
              User variable settings are lost.
            </p></li><li class="listitem"><p>
              Prepared statements are released.
            </p></li><li class="listitem"><p>
              <a class="link" href="sql-syntax.html#handler" title="13.2.4 HANDLER Syntax"><code class="literal">HANDLER</code></a> variables are
              closed.
            </p></li><li class="listitem"><p>
              The value of
              <a class="link" href="functions.html#function_last-insert-id"><code class="literal">LAST_INSERT_ID()</code></a> is reset
              to 0.
            </p></li><li class="listitem"><p>
              Locks acquired with
              <a class="link" href="functions.html#function_get-lock"><code class="literal">GET_LOCK()</code></a> are released.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-reset-connection-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-rollback"></a>27.8.7.61 mysql_rollback()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710573383040"></a><p>
        <code class="literal">my_bool mysql_rollback(MYSQL *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-rollback-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Rolls back the current transaction.
        </p><p>
          The action of this function is subject to the value of the
          <a class="link" href="server-administration.html#sysvar_completion_type"><code class="literal">completion_type</code></a> system
          variable. In particular, if the value of
          <a class="link" href="server-administration.html#sysvar_completion_type"><code class="literal">completion_type</code></a> is
          <code class="literal">RELEASE</code> (or 2), the server performs a
          release after terminating a transaction and closes the client
          connection. Call <a class="link" href="connectors-apis.html#mysql-close" title="27.8.7.5 mysql_close()"><code class="literal">mysql_close()</code></a>
          from the client program to close the connection from the
          client side.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-rollback-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-rollback-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-row-seek"></a>27.8.7.62 mysql_row_seek()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710573369424"></a><p>
        <code class="literal">MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES *result,
        MYSQL_ROW_OFFSET offset)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-row-seek-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Sets the row cursor to an arbitrary row in a query result set.
          The <code class="literal">offset</code> value is a row offset, typically
          a value returned from
          <a class="link" href="connectors-apis.html#mysql-row-tell" title="27.8.7.63 mysql_row_tell()"><code class="literal">mysql_row_tell()</code></a> or from
          <a class="link" href="connectors-apis.html#mysql-row-seek" title="27.8.7.62 mysql_row_seek()"><code class="literal">mysql_row_seek()</code></a>. This value
          is not a row number; to seek to a row within a result set by
          number, use <a class="link" href="connectors-apis.html#mysql-data-seek" title="27.8.7.9 mysql_data_seek()"><code class="literal">mysql_data_seek()</code></a>
          instead.
        </p><p>
          This function requires that the result set structure contains
          the entire result of the query, so
          <a class="link" href="connectors-apis.html#mysql-row-seek" title="27.8.7.62 mysql_row_seek()"><code class="literal">mysql_row_seek()</code></a> may be used
          only in conjunction with
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a>, not with
          <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-row-seek-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          The previous value of the row cursor. This value may be passed
          to a subsequent call to
          <a class="link" href="connectors-apis.html#mysql-row-seek" title="27.8.7.62 mysql_row_seek()"><code class="literal">mysql_row_seek()</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-row-seek-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-row-tell"></a>27.8.7.63 mysql_row_tell()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710573350800"></a><p>
        <code class="literal">MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES
        *result)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-row-tell-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns the current position of the row cursor for the last
          <a class="link" href="connectors-apis.html#mysql-fetch-row" title="27.8.7.21 mysql_fetch_row()"><code class="literal">mysql_fetch_row()</code></a>. This value
          can be used as an argument to
          <a class="link" href="connectors-apis.html#mysql-row-seek" title="27.8.7.62 mysql_row_seek()"><code class="literal">mysql_row_seek()</code></a>.
        </p><p>
          Use <a class="link" href="connectors-apis.html#mysql-row-tell" title="27.8.7.63 mysql_row_tell()"><code class="literal">mysql_row_tell()</code></a> only
          after <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a>,
          not after <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-row-tell-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          The current offset of the row cursor.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-row-tell-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-select-db"></a>27.8.7.64 mysql_select_db()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710573335600"></a><p>
        <code class="literal">int mysql_select_db(MYSQL *mysql, const char
        *db)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-select-db-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Causes the database specified by <code class="literal">db</code> to
          become the default (current) database on the connection
          specified by <code class="literal">mysql</code>. In subsequent queries,
          this database is the default for table references that include
          no explicit database specifier.
        </p><p>
          <a class="link" href="connectors-apis.html#mysql-select-db" title="27.8.7.64 mysql_select_db()"><code class="literal">mysql_select_db()</code></a> fails unless
          the connected user can be authenticated as having permission
          to use the database.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-select-db-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-select-db-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-session-track-get-first"></a>27.8.7.65 mysql_session_track_get_first()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710573314032"></a><a class="indexterm" name="idm140710573312944"></a><p>
        <code class="literal">int mysql_session_track_get_first(MYSQL *mysql, enum
        enum_session_state_type type, const char **data, size_t
        *length)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-session-track-get-first-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          This function fetches the first session state-change
          information received from the server.
        </p><p>
          To control notification for changes to session state, use the
          <a class="link" href="server-administration.html#sysvar_session_track_state_change"><code class="literal">session_track_state_change</code></a>,
          <a class="link" href="server-administration.html#sysvar_session_track_schema"><code class="literal">session_track_schema</code></a>,
          <a class="link" href="server-administration.html#sysvar_session_track_system_variables"><code class="literal">session_track_system_variables</code></a>,
          and <a class="link" href="server-administration.html#sysvar_session_track_gtids"><code class="literal">session_track_gtids</code></a>
          system variables (see
          <a class="xref" href="server-administration.html#server-system-variables" title="5.1.7 Server System Variables">Section 5.1.7, “Server System Variables”</a>).
        </p><p>
          The function parameters are used as follows. These
          descriptions also apply to
          <a class="link" href="connectors-apis.html#mysql-session-track-get-next" title="27.8.7.66 mysql_session_track_get_next()"><code class="literal">mysql_session_track_get_next()</code></a>,
          which takes the same parameters.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <code class="literal">mysql</code>: The connection handler.
            </p></li><li class="listitem"><p>
              <code class="literal">type</code>: The type of information to
              retrieve. Permitted values for this parameter are the
              members of the <code class="literal">enum_session_state_type</code>
              enumeration defined in <code class="filename">mysql_com.h</code>:
            </p><pre data-lang="c" class="programlisting">
enum enum_session_state_type
{
  SESSION_TRACK_SYSTEM_VARIABLES, /* Session system variables */
  SESSION_TRACK_SCHEMA,           /* Current schema */
  SESSION_TRACK_STATE_CHANGE      /* track session state changes */
  SESSION_TRACK_GTIDS,            /* track GTIDs/*
};
</pre><p>
              To make it easy to loop over all possible types of session
              information, the <code class="literal">SESSION_TRACK_BEGIN</code>
              and <code class="literal">SESSION_TRACK_END</code> macros are
              defined to be equal to the first and last members of the
              <code class="literal">enum_session_state_type</code> enumeration.
              The example code shown later in this section demonstrates
              this technique.
            </p></li><li class="listitem"><p>
              <code class="literal">data</code>: The address of a <code class="literal">const
              char *</code> variable. Following a successful call,
              this variable points to the returned data, which should be
              considered read only.
            </p></li><li class="listitem"><p>
              <code class="literal">length</code>: The address of a
              <code class="literal">size_t</code> variable. Following a successful
              call, this variable contains the length of the data
              pointed to by the <code class="literal">data</code> parameter.
</p></li></ul>
</div>
<p>
          Following a successful call, interpret the
          <code class="literal">data</code> and <code class="literal">length</code> values
          according to the <code class="literal">type</code> value, as follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <code class="literal">SESSION_TRACK_SCHEMA</code>:
              <code class="literal">data</code> is the new default schema name and
              <code class="literal">length</code> is the name length.
            </p></li><li class="listitem"><p>
              <code class="literal">SESSION_TRACK_SYSTEM_VARIABLES</code>: When a
              session system variable changes, two values per variable
              are returned (in separate calls). For the first call,
              <code class="literal">data</code> is the variable name and
              <code class="literal">length</code> is the name length. For the
              second call, <code class="literal">data</code> is the variable value
              and <code class="literal">length</code> is the value length. value
              Both data values are represented as strings.
            </p></li><li class="listitem"><p>
              <code class="literal">SESSION_TRACK_STATE_CHANGE</code>:
              <code class="literal">data</code> is a byte containing a boolean
              flag that indicates whether session state changes occurred
              and <code class="literal">length</code> should be 1. The flag is
              represented as an ASCII value, not a binary (for example,
              <code class="literal">'1'</code>, not <code class="literal">0x01</code>).
            </p></li><li class="listitem"><p>
              <code class="literal">SESSION_TRACK_GTIDS</code>:
              <code class="literal">data</code> contains the GTID set information
              and <code class="literal">length</code> is its length.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-session-track-get-first-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-session-track-get-first-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-session-track-get-first-example"></a>Example</h5>

</div>

</div>

</div>
<p>
          The following example shows how to call
          <a class="link" href="connectors-apis.html#mysql-session-track-get-first" title="27.8.7.65 mysql_session_track_get_first()"><code class="literal">mysql_session_track_get_first()</code></a>
          and
          <a class="link" href="connectors-apis.html#mysql-session-track-get-next" title="27.8.7.66 mysql_session_track_get_next()"><code class="literal">mysql_session_track_get_next()</code></a>
          to retrieve and display all available session state-change
          information following successful execution of an SQL statement
          string (represented by <code class="literal">stmt_str</code>).
        </p><pre data-lang="c" class="programlisting">
printf("Execute: %s\n", stmt_str);

if (mysql_query(mysql, stmt_str) != 0)
{
  fprintf(stderr, "Error %u: %s\n",
           mysql_errno(mysql), mysql_error(mysql));
  return;
}

MYSQL_RES *result = mysql_store_result(mysql);
if (result) /* there is a result set to fetch */
{
  /* ... process rows here ... */
  printf("Number of rows returned: %lu\n",
          (unsigned long) mysql_num_rows(result));
  mysql_free_result(result);
}
else        /* there is no result set */
{
  if (mysql_field_count(mysql) == 0)
  {
    printf("Number of rows affected: %lu\n",
            (unsigned long) mysql_affected_rows(mysql));
  }
  else      /* an error occurred */
  {
    fprintf(stderr, "Error %u: %s\n",
             mysql_errno(mysql), mysql_error(mysql));
  }
}

/* extract any available session state-change information */
enum enum_session_state_type type;
for (type = SESSION_TRACK_BEGIN; type &lt;= SESSION_TRACK_END; type++)
{
  const char *data;
  size_t length;

  if (mysql_session_track_get_first(mysql, type, &amp;data, &amp;length) == 0)
  {
    printf("Type=%d:\n", type);
    printf("mysql_session_track_get_first() returns: %*.*s\n",
            (int) length, (int) length, data);

    /* check for more data */
    while (mysql_session_track_get_next(mysql, type, &amp;data, &amp;length) == 0)
    {
      printf("mysql_session_track_get_next() returns: %*.*s\n",
              (int) length, (int) length, data);
    }
  }
}
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-session-track-get-next"></a>27.8.7.66 mysql_session_track_get_next()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710573255472"></a><a class="indexterm" name="idm140710573254384"></a><p>
        <code class="literal">int mysql_session_track_get_next(MYSQL *mysql, enum
        enum_session_state_type type, const char **data, size_t
        *length)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-session-track-get-next-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          This function fetches session state-change information
          received from the server, following that retrieved by
          <a class="link" href="connectors-apis.html#mysql-session-track-get-first" title="27.8.7.65 mysql_session_track_get_first()"><code class="literal">mysql_session_track_get_first()</code></a>.
        </p><p>
          Following a successful call to
          <a class="link" href="connectors-apis.html#mysql-session-track-get-first" title="27.8.7.65 mysql_session_track_get_first()"><code class="literal">mysql_session_track_get_first()</code></a>,
          call
          <a class="link" href="connectors-apis.html#mysql-session-track-get-next" title="27.8.7.66 mysql_session_track_get_next()"><code class="literal">mysql_session_track_get_next()</code></a>
          repeatedly until it returns nonzero to indicate no more
          information is available. The calling sequence for
          <a class="link" href="connectors-apis.html#mysql-session-track-get-next" title="27.8.7.66 mysql_session_track_get_next()"><code class="literal">mysql_session_track_get_next()</code></a>
          is similar to that for
          <a class="link" href="connectors-apis.html#mysql-session-track-get-first" title="27.8.7.65 mysql_session_track_get_first()"><code class="literal">mysql_session_track_get_first()</code></a>.
          For more information and an example that demonstrates both
          functions, see
          <a class="xref" href="connectors-apis.html#mysql-session-track-get-first" title="27.8.7.65 mysql_session_track_get_first()">Section 27.8.7.65, “mysql_session_track_get_first()”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-session-track-get-next-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-session-track-get-next-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-set-character-set"></a>27.8.7.67 mysql_set_character_set()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710573237744"></a><p>
        <code class="literal">int mysql_set_character_set(MYSQL *mysql, const char
        *csname)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-set-character-set-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          This function is used to set the default character set for the
          current connection. The string <code class="literal">csname</code>
          specifies a valid character set name. The connection collation
          becomes the default collation of the character set. This
          function works like the <a class="link" href="sql-syntax.html#set-names" title="13.7.4.3 SET NAMES Syntax"><code class="literal">SET
          NAMES</code></a> statement, but also sets the value of
          <code class="literal">mysql-&gt;charset</code>, and thus affects the
          character set used by
          <a class="link" href="connectors-apis.html#mysql-real-escape-string" title="27.8.7.55 mysql_real_escape_string()"><code class="literal">mysql_real_escape_string()</code></a>
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-set-character-set-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-set-character-set-example"></a>Example</h5>

</div>

</div>

</div>
<pre data-lang="c" class="programlisting">
MYSQL mysql;

mysql_init(&amp;mysql);
if (!mysql_real_connect(&amp;mysql,"host","user","passwd","database",0,NULL,0))
{
    fprintf(stderr, "Failed to connect to database: Error: %s\n",
          mysql_error(&amp;mysql));
}

if (!mysql_set_character_set(&amp;mysql, "utf8"))
{
    printf("New client character set: %s\n",
           mysql_character_set_name(&amp;mysql));
}
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-set-local-infile-default"></a>27.8.7.68 mysql_set_local_infile_default()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710573223792"></a><a class="indexterm" name="idm140710573222704"></a><p>
        <code class="literal">void mysql_set_local_infile_default(MYSQL
        *mysql);</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-set-local-infile-default-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Sets the <a class="link" href="sql-syntax.html#load-data" title="13.2.6 LOAD DATA INFILE Syntax"><code class="literal">LOAD DATA
          LOCAL INFILE</code></a> callback functions to the defaults used
          internally by the C client library. The library calls this
          function automatically if
          <a class="link" href="connectors-apis.html#mysql-set-local-infile-handler" title="27.8.7.69 mysql_set_local_infile_handler()"><code class="literal">mysql_set_local_infile_handler()</code></a>
          has not been called or does not supply valid functions for
          each of its callbacks.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-set-local-infile-default-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-set-local-infile-default-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-set-local-infile-handler"></a>27.8.7.69 mysql_set_local_infile_handler()</h4>

</div>

</div>

</div>
<p>
        <code class="literal">void mysql_set_local_infile_handler(MYSQL *mysql, int
        (*local_infile_init)(void **, const char *, void *), int
        (*local_infile_read)(void *, char *, unsigned int), void
        (*local_infile_end)(void *), int (*local_infile_error)(void *,
        char*, unsigned int), void *userdata);</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-set-local-infile-handler-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          This function installs callbacks to be used during the
          execution of <a class="link" href="sql-syntax.html#load-data" title="13.2.6 LOAD DATA INFILE Syntax"><code class="literal">LOAD
          DATA LOCAL INFILE</code></a> statements. It enables application
          programs to exert control over local (client-side) data file
          reading. The arguments are the connection handler, a set of
          pointers to callback functions, and a pointer to a data area
          that the callbacks can use to share information.
        </p><p>
          To use
          <a class="link" href="connectors-apis.html#mysql-set-local-infile-handler" title="27.8.7.69 mysql_set_local_infile_handler()"><code class="literal">mysql_set_local_infile_handler()</code></a>,
          you must write the following callback functions:
        </p><pre data-lang="c" class="programlisting">
int
local_infile_init(void **ptr, const char *filename, void *userdata);
</pre><p>
          The initialization function. This is called once to do any
          setup necessary, open the data file, allocate data structures,
          and so forth. The first <code class="literal">void**</code> argument is
          a pointer to a pointer. You can set the pointer (that is,
          <code class="literal">*ptr</code>) to a value that will be passed to
          each of the other callbacks (as a <code class="literal">void*</code>).
          The callbacks can use this pointed-to value to maintain state
          information. The <code class="literal">userdata</code> argument is the
          same value that is passed to
          <a class="link" href="connectors-apis.html#mysql-set-local-infile-handler" title="27.8.7.69 mysql_set_local_infile_handler()"><code class="literal">mysql_set_local_infile_handler()</code></a>.
        </p><p>
          Make the initialization function return zero for success,
          nonzero for an error.
        </p><pre data-lang="c" class="programlisting">
int
local_infile_read(void *ptr, char *buf, unsigned int buf_len);
</pre><p>
          The data-reading function. This is called repeatedly to read
          the data file. <code class="literal">buf</code> points to the buffer
          where the read data is stored, and <code class="literal">buf_len</code>
          is the maximum number of bytes that the callback can read and
          store in the buffer. (It can read fewer bytes, but should not
          read more.)
        </p><p>
          The return value is the number of bytes read, or zero when no
          more data could be read (this indicates EOF). Return a value
          less than zero if an error occurs.
        </p><pre data-lang="c" class="programlisting">
void
local_infile_end(void *ptr)
</pre><p>
          The termination function. This is called once after
          <code class="literal">local_infile_read()</code> has returned zero (EOF)
          or an error. Within this function, deallocate any memory
          allocated by <code class="literal">local_infile_init()</code> and
          perform any other cleanup necessary. It is invoked even if the
          initialization function returns an error.
        </p><pre data-lang="c" class="programlisting">
int
local_infile_error(void *ptr,
                   char *error_msg,
                   unsigned int error_msg_len);
</pre><p>
          The error-handling function. This is called to get a textual
          error message to return to the user in case any of your other
          functions returns an error. <code class="literal">error_msg</code>
          points to the buffer into which the message is written, and
          <code class="literal">error_msg_len</code> is the length of the buffer.
          Write the message as a null-terminated string, at most
          <code class="literal">error_msg_len</code>−1 bytes long.
        </p><p>
          The return value is the error number.
        </p><p>
          Typically, the other callbacks store the error message in the
          data structure pointed to by <code class="literal">ptr</code>, so that
          <code class="literal">local_infile_error()</code> can copy the message
          from there into <code class="literal">error_msg</code>.
        </p><p>
          After calling
          <a class="link" href="connectors-apis.html#mysql-set-local-infile-handler" title="27.8.7.69 mysql_set_local_infile_handler()"><code class="literal">mysql_set_local_infile_handler()</code></a>
          in your C code and passing pointers to your callback
          functions, you can then issue a
          <a class="link" href="sql-syntax.html#load-data" title="13.2.6 LOAD DATA INFILE Syntax"><code class="literal">LOAD DATA LOCAL
          INFILE</code></a> statement (for example, by using
          <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a>). The client
          library automatically invokes your callbacks. The file name
          specified in <a class="link" href="sql-syntax.html#load-data" title="13.2.6 LOAD DATA INFILE Syntax"><code class="literal">LOAD
          DATA LOCAL INFILE</code></a> will be passed as the second
          parameter to the <code class="literal">local_infile_init()</code>
          callback.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-set-local-infile-handler-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-set-local-infile-handler-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-set-server-option"></a>27.8.7.70 mysql_set_server_option()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710573173408"></a><p>
        <code class="literal">int mysql_set_server_option(MYSQL *mysql, enum
        enum_mysql_set_option option)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-set-server-option-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Enables or disables an option for the connection.
          <code class="literal">option</code> can have one of the following
          values.
</p>
<div class="informaltable">
<table summary="Options for mysql_set_server_option() and a description of each option."><col width="50%"><col width="50%"><thead><tr>
              <th scope="col">Option</th>
              <th scope="col">Description</th>
            </tr></thead><tbody><tr>
              <td scope="row"><code class="literal">MYSQL_OPTION_MULTI_STATEMENTS_ON</code></td>
              <td>Enable multiple-statement support</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_OPTION_MULTI_STATEMENTS_OFF</code></td>
              <td>Disable multiple-statement support</td>
</tr></tbody></table>
</div>
<p>
          If you enable multiple-statement support, you should retrieve
          results from calls to
          <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a> or
          <a class="link" href="connectors-apis.html#mysql-real-query" title="27.8.7.57 mysql_real_query()"><code class="literal">mysql_real_query()</code></a> by using a
          loop that calls
          <a class="link" href="connectors-apis.html#mysql-next-result" title="27.8.7.47 mysql_next_result()"><code class="literal">mysql_next_result()</code></a> to
          determine whether there are more results. For an example, see
          <a class="xref" href="connectors-apis.html#c-api-multiple-queries" title="27.8.16 C API Multiple Statement Execution Support">Section 27.8.16, “C API Multiple Statement Execution Support”</a>.
        </p><p>
          Enabling multiple-statement support with
          <code class="literal">MYSQL_OPTION_MULTI_STATEMENTS_ON</code> does not
          have quite the same effect as enabling it by passing the
          <code class="literal">CLIENT_MULTI_STATEMENTS</code> flag to
          <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a>:
          <code class="literal">CLIENT_MULTI_STATEMENTS</code> also enables
          <code class="literal">CLIENT_MULTI_RESULTS</code>. If you are using the
          <a class="link" href="sql-syntax.html#call" title="13.2.1 CALL Syntax"><code class="literal">CALL</code></a> SQL statement in your
          programs, multiple-result support must be enabled; this means
          that <code class="literal">MYSQL_OPTION_MULTI_STATEMENTS_ON</code> by
          itself is insufficient to permit the use of
          <a class="link" href="sql-syntax.html#call" title="13.2.1 CALL Syntax"><code class="literal">CALL</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-set-server-option-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-set-server-option-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_er_unknown_com_error"><code class="literal">ER_UNKNOWN_COM_ERROR</code></a>
            </p><p>
              The server did not support
              <a class="link" href="connectors-apis.html#mysql-set-server-option" title="27.8.7.70 mysql_set_server_option()"><code class="literal">mysql_set_server_option()</code></a>
              (which is the case that the server is older than 4.1.1) or
              the server did not support the option one tried to set.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-shutdown"></a>27.8.7.71 mysql_shutdown()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710573128608"></a><p>
        <code class="literal">int mysql_shutdown(MYSQL *mysql, enum
        mysql_enum_shutdown_level shutdown_level)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-shutdown-description"></a>Description</h5>

</div>

</div>

</div>

<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
            <code class="literal">mysql_shutdown()</code> is deprecated and will
            be removed in a future version of MySQL. Instead, use
            <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a> to execute a
            <a class="link" href="sql-syntax.html#shutdown" title="13.7.6.7 SHUTDOWN Syntax"><code class="literal">SHUTDOWN</code></a> statement.
</p>
</div>
<p>
          Asks the database server to shut down. The connected user must
          have the <a class="link" href="security.html#priv_shutdown"><code class="literal">SHUTDOWN</code></a> privilege.
          MySQL servers support only one type of shutdown;
          <code class="literal">shutdown_level</code> must be equal to
          <code class="literal">SHUTDOWN_DEFAULT</code>. Dynamically linked
          executables which have been compiled with older versions of
          the <code class="literal">libmysqlclient</code> headers and call
          <a class="link" href="connectors-apis.html#mysql-shutdown" title="27.8.7.71 mysql_shutdown()"><code class="literal">mysql_shutdown()</code></a> need to be
          used with the old <code class="literal">libmysqlclient</code> dynamic
          library.
        </p><p>
          An alternative to
          <a class="link" href="connectors-apis.html#mysql-shutdown" title="27.8.7.71 mysql_shutdown()"><code class="literal">mysql_shutdown()</code></a> is to use the
          <a class="link" href="sql-syntax.html#shutdown" title="13.7.6.7 SHUTDOWN Syntax"><code class="literal">SHUTDOWN</code></a> SQL statement.
        </p><p>
          The shutdown process is described in
          <a class="xref" href="server-administration.html#server-shutdown" title="5.1.15 The Server Shutdown Process">Section 5.1.15, “The Server Shutdown Process”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-shutdown-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-shutdown-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-sqlstate"></a>27.8.7.72 mysql_sqlstate()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710573096464"></a><p>
        <code class="literal">const char *mysql_sqlstate(MYSQL *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-sqlstate-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns a null-terminated string containing the SQLSTATE error
          code for the most recently executed SQL statement. The error
          code consists of five characters. <code class="literal">'00000'</code>
          means <span class="quote">“<span class="quote">no error.</span>”</span> The values are specified by
          ANSI SQL and ODBC. For a list of possible values, see
          <a class="xref" href="error-handling.html" title="Appendix B Errors, Error Codes, and Common Problems">Appendix B, <i>Errors, Error Codes, and Common Problems</i></a>.
        </p><p>
          SQLSTATE values returned by
          <a class="link" href="connectors-apis.html#mysql-sqlstate" title="27.8.7.72 mysql_sqlstate()"><code class="literal">mysql_sqlstate()</code></a> differ from
          MySQL-specific error numbers returned by
          <a class="link" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()"><code class="literal">mysql_errno()</code></a>. For example,
          the <a class="link" href="programs.html#mysql" title="4.5.1 mysql — The MySQL Command-Line Tool"><span class="command"><strong>mysql</strong></span></a> client program displays errors
          using the following format, where <code class="literal">1146</code> is
          the <a class="link" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()"><code class="literal">mysql_errno()</code></a> value and
          <code class="literal">'42S02'</code> is the corresponding
          <a class="link" href="connectors-apis.html#mysql-sqlstate" title="27.8.7.72 mysql_sqlstate()"><code class="literal">mysql_sqlstate()</code></a> value:
        </p><pre data-lang="sql" class="programlisting">
shell&gt; <strong class="userinput"><code>SELECT * FROM no_such_table;</code></strong>
ERROR 1146 (42S02): Table 'test.no_such_table' doesn't exist
</pre><p>
          Not all MySQL error numbers are mapped to SQLSTATE error
          codes. The value <code class="literal">'HY000'</code> (general error) is
          used for unmapped error numbers.
        </p><p>
          If you call <a class="link" href="connectors-apis.html#mysql-sqlstate" title="27.8.7.72 mysql_sqlstate()"><code class="literal">mysql_sqlstate()</code></a>
          after <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a>
          fails, <a class="link" href="connectors-apis.html#mysql-sqlstate" title="27.8.7.72 mysql_sqlstate()"><code class="literal">mysql_sqlstate()</code></a> might
          not return a useful value. For example, this happens if a host
          is blocked by the server and the connection is closed without
          any SQLSTATE value being sent to the client.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-sqlstate-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          A null-terminated character string containing the SQLSTATE
          error code.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-sqlstate-see-also"></a>See Also</h5>

</div>

</div>

</div>
<p>
          See <a class="xref" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()">Section 27.8.7.14, “mysql_errno()”</a>,
          <a class="xref" href="connectors-apis.html#mysql-error" title="27.8.7.15 mysql_error()">Section 27.8.7.15, “mysql_error()”</a>, and
          <a class="xref" href="connectors-apis.html#mysql-stmt-sqlstate" title="27.8.11.27 mysql_stmt_sqlstate()">Section 27.8.11.27, “mysql_stmt_sqlstate()”</a>.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-ssl-set"></a>27.8.7.73 mysql_ssl_set()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710573068176"></a><p>
        <code class="literal">my_bool mysql_ssl_set(MYSQL *mysql, const char *key,
        const char *cert, const char *ca, const char *capath, const char
        *cipher)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-ssl-set-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          <a class="link" href="connectors-apis.html#mysql-ssl-set" title="27.8.7.73 mysql_ssl_set()"><code class="literal">mysql_ssl_set()</code></a> is used for
          establishing encrypted connections using SSL. The
          <code class="literal">mysql</code> argument must be a valid connection
          handler. Any unused SSL arguments may be given as
          <code class="literal">NULL</code>.
        </p><p>
          If used, <a class="link" href="connectors-apis.html#mysql-ssl-set" title="27.8.7.73 mysql_ssl_set()"><code class="literal">mysql_ssl_set()</code></a> must
          be called before
          <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a>.
          <a class="link" href="connectors-apis.html#mysql-ssl-set" title="27.8.7.73 mysql_ssl_set()"><code class="literal">mysql_ssl_set()</code></a> does nothing
          unless SSL support is enabled in the client library.
        </p><p>
          It is optional to call
          <a class="link" href="connectors-apis.html#mysql-ssl-set" title="27.8.7.73 mysql_ssl_set()"><code class="literal">mysql_ssl_set()</code></a> to obtain an
          encrypted connection because by default, MySQL programs
          attempt to connect using encryption if the server supports
          encrypted connections, falling back to an unencrypted
          connection if an encrypted connection cannot be established
          (see <a class="xref" href="security.html#using-encrypted-connections" title="6.4.1 Configuring MySQL to Use Encrypted Connections">Section 6.4.1, “Configuring MySQL to Use Encrypted Connections”</a>).
          <a class="link" href="connectors-apis.html#mysql-ssl-set" title="27.8.7.73 mysql_ssl_set()"><code class="literal">mysql_ssl_set()</code></a> may be useful
          to applications that must specify particular certificate and
          key files, encryption ciphers, and so forth.
        </p><p>
          <a class="link" href="connectors-apis.html#mysql-ssl-set" title="27.8.7.73 mysql_ssl_set()"><code class="literal">mysql_ssl_set()</code></a> specifies SSL
          information such as certificate and key files for establishing
          an encrypted connection if such connections are available, but
          does not enforce any requirement that the connection obtained
          be encrypted. To require an encrypted connection, use the
          technique described in
          <a class="xref" href="connectors-apis.html#c-api-encrypted-connections" title="27.8.15 C API Encrypted Connection Support">Section 27.8.15, “C API Encrypted Connection Support”</a>.
        </p><p>
          For additional security relative to that provided by the
          default encryption, clients can supply a CA certificate
          matching the one used by the server and enable host name
          identity verification. In this way, the server and client
          place their trust in the same CA certificate and the client
          verifies that the host to which it connected is the one
          intended. For details, see
          <a class="xref" href="connectors-apis.html#c-api-encrypted-connections" title="27.8.15 C API Encrypted Connection Support">Section 27.8.15, “C API Encrypted Connection Support”</a>.
        </p><p>
          <a class="link" href="connectors-apis.html#mysql-ssl-set" title="27.8.7.73 mysql_ssl_set()"><code class="literal">mysql_ssl_set()</code></a> is a
          convenience function that is essentially equivalent to this
          set of <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> calls:
        </p><pre data-lang="c" class="programlisting">
mysql_options(mysql, MYSQL_OPT_SSL_KEY,    key);
mysql_options(mysql, MYSQL_OPT_SSL_CERT,   cert);
mysql_options(mysql, MYSQL_OPT_SSL_CA,     ca);
mysql_options(mysql, MYSQL_OPT_SSL_CAPATH, capath);
mysql_options(mysql, MYSQL_OPT_SSL_CIPHER, cipher);
</pre><p>
          Because of that equivalence, applications can, instead of
          calling <a class="link" href="connectors-apis.html#mysql-ssl-set" title="27.8.7.73 mysql_ssl_set()"><code class="literal">mysql_ssl_set()</code></a>, call
          <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> directly,
          omitting calls for those options for which the option value is
          <code class="literal">NULL</code>. Moreover,
          <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> offers
          encrypted-connection options not available using
          <a class="link" href="connectors-apis.html#mysql-ssl-set" title="27.8.7.73 mysql_ssl_set()"><code class="literal">mysql_ssl_set()</code></a>, such as
          <code class="literal">MYSQL_OPT_SSL_MODE</code> to specify the security
          state of the connection, and
          <code class="literal">MYSQL_OPT_TLS_VERSION</code> to specify the
          protocols permitted by the client for encrypted connections.
        </p><p>
          Arguments:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <code class="literal">mysql</code>: The connection handler returned
              from <a class="link" href="connectors-apis.html#mysql-init" title="27.8.7.37 mysql_init()"><code class="literal">mysql_init()</code></a>.
            </p></li><li class="listitem"><p>
              <code class="literal">key</code>: The path name of the client
              private key file.
            </p></li><li class="listitem"><p>
              <code class="literal">cert</code>: The path name of the client
              public key certificate file.
            </p></li><li class="listitem"><p>
              <code class="literal">ca</code>: The path name of the Certificate
              Authority (CA) certificate file. This option, if used,
              must specify the same certificate used by the server.
            </p></li><li class="listitem"><p>
              <code class="literal">capath</code>: The path name of the directory
              that contains trusted SSL CA certificate files.
            </p></li><li class="listitem"><p>
              <code class="literal">cipher</code>: The list of permitted ciphers
              for SSL encryption.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-ssl-set-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          This function always returns <code class="literal">0</code>. If SSL
          setup is incorrect, a subsequent
          <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a> call
          returns an error when you attempt to connect.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stat"></a>27.8.7.74 mysql_stat()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710573020112"></a><p>
        <code class="literal">const char *mysql_stat(MYSQL *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stat-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns a character string containing information similar to
          that provided by the <a class="link" href="programs.html#mysqladmin" title="4.5.2 mysqladmin — Client for Administering a MySQL Server"><span class="command"><strong>mysqladmin status</strong></span></a>
          command. This includes uptime in seconds and the number of
          running threads, questions, reloads, and open tables.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stat-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          A character string describing the server status.
          <code class="literal">NULL</code> if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stat-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-store-result"></a>27.8.7.75 mysql_store_result()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710572999728"></a><p>
        <code class="literal">MYSQL_RES *mysql_store_result(MYSQL *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-store-result-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          After invoking <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a>
          or <a class="link" href="connectors-apis.html#mysql-real-query" title="27.8.7.57 mysql_real_query()"><code class="literal">mysql_real_query()</code></a>, you
          must call <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a>
          or <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a> for
          every statement that successfully produces a result set
          (<a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a>,
          <a class="link" href="sql-syntax.html#show" title="13.7.5 SHOW Syntax"><code class="literal">SHOW</code></a>,
          <a class="link" href="sql-syntax.html#describe" title="13.8.1 DESCRIBE Syntax"><code class="literal">DESCRIBE</code></a>,
          <a class="link" href="sql-syntax.html#explain" title="13.8.2 EXPLAIN Syntax"><code class="literal">EXPLAIN</code></a>,
          <a class="link" href="sql-syntax.html#check-table" title="13.7.2.2 CHECK TABLE Syntax"><code class="literal">CHECK TABLE</code></a>, and so forth). You
          must also call
          <a class="link" href="connectors-apis.html#mysql-free-result" title="27.8.7.25 mysql_free_result()"><code class="literal">mysql_free_result()</code></a> after you
          are done with the result set.
        </p><p>
          You need not call
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a> or
          <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a> for other
          statements, but it does not do any harm or cause any notable
          performance degradation if you call
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a> in all
          cases. You can detect whether the statement has a result set
          by checking whether
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a> returns a
          nonzero value (more about this later).
        </p><p>
          If you enable multiple-statement support, you should retrieve
          results from calls to
          <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a> or
          <a class="link" href="connectors-apis.html#mysql-real-query" title="27.8.7.57 mysql_real_query()"><code class="literal">mysql_real_query()</code></a> by using a
          loop that calls
          <a class="link" href="connectors-apis.html#mysql-next-result" title="27.8.7.47 mysql_next_result()"><code class="literal">mysql_next_result()</code></a> to
          determine whether there are more results. For an example, see
          <a class="xref" href="connectors-apis.html#c-api-multiple-queries" title="27.8.16 C API Multiple Statement Execution Support">Section 27.8.16, “C API Multiple Statement Execution Support”</a>.
        </p><p>
          If you want to know whether a statement should return a result
          set, you can use
          <a class="link" href="connectors-apis.html#mysql-field-count" title="27.8.7.22 mysql_field_count()"><code class="literal">mysql_field_count()</code></a> to check
          for this. See <a class="xref" href="connectors-apis.html#mysql-field-count" title="27.8.7.22 mysql_field_count()">Section 27.8.7.22, “mysql_field_count()”</a>.
        </p><p>
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a> reads the
          entire result of a query to the client, allocates a
          <code class="literal">MYSQL_RES</code> structure, and places the result
          into this structure.
        </p><p>
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a> returns a
          null pointer if the statement did not return a result set (for
          example, if it was an <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT</code></a>
          statement).
        </p><p>
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a> also
          returns a null pointer if reading of the result set failed.
          You can check whether an error occurred by checking whether
          <a class="link" href="connectors-apis.html#mysql-error" title="27.8.7.15 mysql_error()"><code class="literal">mysql_error()</code></a> returns a
          nonempty string, <a class="link" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()"><code class="literal">mysql_errno()</code></a>
          returns nonzero, or
          <a class="link" href="connectors-apis.html#mysql-field-count" title="27.8.7.22 mysql_field_count()"><code class="literal">mysql_field_count()</code></a> returns
          zero.
        </p><p>
          An empty result set is returned if there are no rows returned.
          (An empty result set differs from a null pointer as a return
          value.)
        </p><p>
          After you have called
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a> and
          gotten back a result that is not a null pointer, you can call
          <a class="link" href="connectors-apis.html#mysql-num-rows" title="27.8.7.49 mysql_num_rows()"><code class="literal">mysql_num_rows()</code></a> to find out
          how many rows are in the result set.
        </p><p>
          You can call <a class="link" href="connectors-apis.html#mysql-fetch-row" title="27.8.7.21 mysql_fetch_row()"><code class="literal">mysql_fetch_row()</code></a>
          to fetch rows from the result set, or
          <a class="link" href="connectors-apis.html#mysql-row-seek" title="27.8.7.62 mysql_row_seek()"><code class="literal">mysql_row_seek()</code></a> and
          <a class="link" href="connectors-apis.html#mysql-row-tell" title="27.8.7.63 mysql_row_tell()"><code class="literal">mysql_row_tell()</code></a> to obtain or
          set the current row position within the result set.
        </p><p>
          See <a class="xref" href="connectors-apis.html#null-mysql-store-result" title="27.8.21.1 Why mysql_store_result() Sometimes Returns NULL After mysql_query() Returns Success">Section 27.8.21.1, “Why mysql_store_result() Sometimes Returns NULL After mysql_query()
        Returns Success”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-store-result-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          A <code class="literal">MYSQL_RES</code> result structure with the
          results. <code class="literal">NULL</code> (0) if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-store-result-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a> resets
          <a class="link" href="connectors-apis.html#mysql-error" title="27.8.7.15 mysql_error()"><code class="literal">mysql_error()</code></a> and
          <a class="link" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()"><code class="literal">mysql_errno()</code></a> if it succeeds.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_out_of_memory"><code class="literal">CR_OUT_OF_MEMORY</code></a>
            </p><p>
              Out of memory.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-thread-id"></a>27.8.7.76 mysql_thread_id()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710572928064"></a><p>
        <code class="literal">unsigned long mysql_thread_id(MYSQL *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-thread-id-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns the thread ID of the current connection. This value
          can be used as an argument to
          <a class="link" href="connectors-apis.html#mysql-kill" title="27.8.7.39 mysql_kill()"><code class="literal">mysql_kill()</code></a> to kill the
          thread.
        </p><p>
          If the connection is lost and you reconnect with
          <a class="link" href="connectors-apis.html#mysql-ping" title="27.8.7.52 mysql_ping()"><code class="literal">mysql_ping()</code></a>, the thread ID
          changes. This means you should not get the thread ID and store
          it for later. You should get it when you need it.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
            This function does not work correctly if thread IDs become
            larger than 32 bits, which can occur on some systems. To
            avoid problems with
            <a class="link" href="connectors-apis.html#mysql-thread-id" title="27.8.7.76 mysql_thread_id()"><code class="literal">mysql_thread_id()</code></a>, do not
            use it. To get the connection ID, execute a <code class="literal">SELECT
            CONNECTION_ID()</code> query and retrieve the result.
</p>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-thread-id-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          The thread ID of the current connection.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-thread-id-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-use-result"></a>27.8.7.77 mysql_use_result()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710572913408"></a><p>
        <code class="literal">MYSQL_RES *mysql_use_result(MYSQL *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-use-result-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          After invoking <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a>
          or <a class="link" href="connectors-apis.html#mysql-real-query" title="27.8.7.57 mysql_real_query()"><code class="literal">mysql_real_query()</code></a>, you
          must call <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a>
          or <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a> for
          every statement that successfully produces a result set
          (<a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a>,
          <a class="link" href="sql-syntax.html#show" title="13.7.5 SHOW Syntax"><code class="literal">SHOW</code></a>,
          <a class="link" href="sql-syntax.html#describe" title="13.8.1 DESCRIBE Syntax"><code class="literal">DESCRIBE</code></a>,
          <a class="link" href="sql-syntax.html#explain" title="13.8.2 EXPLAIN Syntax"><code class="literal">EXPLAIN</code></a>,
          <a class="link" href="sql-syntax.html#check-table" title="13.7.2.2 CHECK TABLE Syntax"><code class="literal">CHECK TABLE</code></a>, and so forth). You
          must also call
          <a class="link" href="connectors-apis.html#mysql-free-result" title="27.8.7.25 mysql_free_result()"><code class="literal">mysql_free_result()</code></a> after you
          are done with the result set.
        </p><p>
          <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a> initiates a
          result set retrieval but does not actually read the result set
          into the client like
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a> does.
          Instead, each row must be retrieved individually by making
          calls to <a class="link" href="connectors-apis.html#mysql-fetch-row" title="27.8.7.21 mysql_fetch_row()"><code class="literal">mysql_fetch_row()</code></a>.
          This reads the result of a query directly from the server
          without storing it in a temporary table or local buffer, which
          is somewhat faster and uses much less memory than
          <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a>. The
          client allocates memory only for the current row and a
          communication buffer that may grow up to
          <a class="link" href="server-administration.html#sysvar_max_allowed_packet"><code class="literal">max_allowed_packet</code></a> bytes.
        </p><p>
          On the other hand, you should not use
          <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a> for locking
          reads if you are doing a lot of processing for each row on the
          client side, or if the output is sent to a screen on which the
          user may type a <code class="literal">^S</code> (stop scroll). This ties
          up the server and prevent other threads from updating any
          tables from which the data is being fetched.
        </p><p>
          When using <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a>,
          you must execute
          <a class="link" href="connectors-apis.html#mysql-fetch-row" title="27.8.7.21 mysql_fetch_row()"><code class="literal">mysql_fetch_row()</code></a> until a
          <code class="literal">NULL</code> value is returned, otherwise, the
          unfetched rows are returned as part of the result set for your
          next query. The C API gives the error <code class="literal">Commands out of
          sync; you can't run this command now</code> if you forget
          to do this!
        </p><p>
          You may not use
          <a class="link" href="connectors-apis.html#mysql-data-seek" title="27.8.7.9 mysql_data_seek()"><code class="literal">mysql_data_seek()</code></a>,
          <a class="link" href="connectors-apis.html#mysql-row-seek" title="27.8.7.62 mysql_row_seek()"><code class="literal">mysql_row_seek()</code></a>,
          <a class="link" href="connectors-apis.html#mysql-row-tell" title="27.8.7.63 mysql_row_tell()"><code class="literal">mysql_row_tell()</code></a>,
          <a class="link" href="connectors-apis.html#mysql-num-rows" title="27.8.7.49 mysql_num_rows()"><code class="literal">mysql_num_rows()</code></a>, or
          <a class="link" href="connectors-apis.html#mysql-affected-rows" title="27.8.7.1 mysql_affected_rows()"><code class="literal">mysql_affected_rows()</code></a> with a
          result returned from
          <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a>, nor may
          you issue other queries until
          <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a> has
          finished. (However, after you have fetched all the rows,
          <a class="link" href="connectors-apis.html#mysql-num-rows" title="27.8.7.49 mysql_num_rows()"><code class="literal">mysql_num_rows()</code></a> accurately
          returns the number of rows fetched.)
        </p><p>
          You must call
          <a class="link" href="connectors-apis.html#mysql-free-result" title="27.8.7.25 mysql_free_result()"><code class="literal">mysql_free_result()</code></a> once you
          are done with the result set.
        </p><p>
          When using the <code class="literal">libmysqld</code> embedded server,
          the memory benefits are essentially lost because memory usage
          incrementally increases with each row retrieved until
          <a class="link" href="connectors-apis.html#mysql-free-result" title="27.8.7.25 mysql_free_result()"><code class="literal">mysql_free_result()</code></a> is called.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-use-result-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          A <code class="literal">MYSQL_RES</code> result structure.
          <code class="literal">NULL</code> if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-use-result-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a> resets
          <a class="link" href="connectors-apis.html#mysql-error" title="27.8.7.15 mysql_error()"><code class="literal">mysql_error()</code></a> and
          <a class="link" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()"><code class="literal">mysql_errno()</code></a> if it succeeds.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_out_of_memory"><code class="literal">CR_OUT_OF_MEMORY</code></a>
            </p><p>
              Out of memory.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-warning-count"></a>27.8.7.78 mysql_warning_count()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710572845728"></a><p>
        <code class="literal">unsigned int mysql_warning_count(MYSQL
        *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-warning-count-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns the number of errors, warnings, and notes generated
          during execution of the previous SQL statement.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-warning-count-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          The warning count.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-warning-count-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="c-api-prepared-statements"></a>27.8.8 C API Prepared Statements</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140710572836080"></a><p>
      The MySQL client/server protocol provides for the use of prepared
      statements. This capability uses the <code class="literal">MYSQL_STMT</code>
      statement handler data structure returned by the
      <a class="link" href="connectors-apis.html#mysql-stmt-init" title="27.8.11.15 mysql_stmt_init()"><code class="literal">mysql_stmt_init()</code></a> initialization
      function. Prepared execution is an efficient way to execute a
      statement more than once. The statement is first parsed to prepare
      it for execution. Then it is executed one or more times at a later
      time, using the statement handler returned by the initialization
      function.
    </p><p>
      Prepared execution is faster than direct execution for statements
      executed more than once, primarily because the query is parsed
      only once. In the case of direct execution, the query is parsed
      every time it is executed. Prepared execution also can provide a
      reduction of network traffic because for each execution of the
      prepared statement, it is necessary only to send the data for the
      parameters.
    </p><p>
      Prepared statements might not provide a performance increase in
      some situations. For best results, test your application both with
      prepared and nonprepared statements and choose whichever yields
      best performance.
    </p><p>
      Another advantage of prepared statements is that it uses a binary
      protocol that makes data transfer between client and server more
      efficient.
    </p><p>
      For a list of SQL statements that can be used as prepared
      statements, see <a class="xref" href="sql-syntax.html#sql-syntax-prepared-statements" title="13.5 Prepared SQL Statement Syntax">Section 13.5, “Prepared SQL Statement Syntax”</a>.
    </p><p>
      Metadata changes to tables or views referred to by prepared
      statements are detected and cause automatic repreparation of the
      statement when it is next executed. For more information, see
      <a class="xref" href="optimization.html#statement-caching" title="8.10.4 Caching of Prepared Statements and Stored Programs">Section 8.10.4, “Caching of Prepared Statements and Stored Programs”</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="c-api-prepared-statement-data-structures"></a>27.8.9 C API Prepared Statement Data Structures</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="connectors-apis.html#c-api-prepared-statement-type-codes">27.8.9.1 C API Prepared Statement Type Codes</a></span></dt><dt><span class="section"><a href="connectors-apis.html#c-api-prepared-statement-type-conversions">27.8.9.2 C API Prepared Statement Type Conversions</a></span></dt></dl>
</div>
<a class="indexterm" name="idm140710572826240"></a><a class="indexterm" name="idm140710572824736"></a><p>
      Prepared statements use several data structures:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          To obtain a statement handler, pass a <code class="literal">MYSQL</code>
          connection handler to
          <a class="link" href="connectors-apis.html#mysql-stmt-init" title="27.8.11.15 mysql_stmt_init()"><code class="literal">mysql_stmt_init()</code></a>, which
          returns a pointer to a <code class="literal">MYSQL_STMT</code> data
          structure. This structure is used for further operations with
          the statement. To specify the statement to prepare, pass the
          <code class="literal">MYSQL_STMT</code> pointer and the statement string
          to <a class="link" href="connectors-apis.html#mysql-stmt-prepare" title="27.8.11.21 mysql_stmt_prepare()"><code class="literal">mysql_stmt_prepare()</code></a>.
        </p></li><li class="listitem"><p>
          To provide input parameters for a prepared statement, set up
          <code class="literal">MYSQL_BIND</code> structures and pass them to
          <a class="link" href="connectors-apis.html#mysql-stmt-bind-param" title="27.8.11.4 mysql_stmt_bind_param()"><code class="literal">mysql_stmt_bind_param()</code></a>. To
          receive output column values, set up
          <code class="literal">MYSQL_BIND</code> structures and pass them to
          <a class="link" href="connectors-apis.html#mysql-stmt-bind-result" title="27.8.11.5 mysql_stmt_bind_result()"><code class="literal">mysql_stmt_bind_result()</code></a>.
        </p></li><li class="listitem"><p>
          The <code class="literal">MYSQL_TIME</code> structure is used to
          transfer temporal data in both directions.
</p></li></ul>
</div>
<p>
      The following discussion describes the prepared statement data
      types in detail. For examples that show how to use them, see
      <a class="xref" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()">Section 27.8.11.10, “mysql_stmt_execute()”</a>, and
      <a class="xref" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()">Section 27.8.11.11, “mysql_stmt_fetch()”</a>.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <a class="indexterm" name="idm140710572807056"></a>

          <code class="literal">MYSQL_STMT</code>
        </p><p>
          This structure is a handler for a prepared statement. A
          handler is created by calling
          <a class="link" href="connectors-apis.html#mysql-stmt-init" title="27.8.11.15 mysql_stmt_init()"><code class="literal">mysql_stmt_init()</code></a>, which
          returns a pointer to a <code class="literal">MYSQL_STMT</code>. The
          handler is used for all subsequent operations with the
          statement until you close it with
          <a class="link" href="connectors-apis.html#mysql-stmt-close" title="27.8.11.6 mysql_stmt_close()"><code class="literal">mysql_stmt_close()</code></a>, at which
          point the handler becomes invalid and should no longer be
          used.
        </p><p>
          The <code class="literal">MYSQL_STMT</code> structure has no members
          intended for application use. Applications should not try to
          copy a <code class="literal">MYSQL_STMT</code> structure. There is no
          guarantee that such a copy will be usable.
        </p><p>
          Multiple statement handlers can be associated with a single
          connection. The limit on the number of handlers depends on the
          available system resources.
        </p></li><li class="listitem"><p>
          <a class="indexterm" name="idm140710572798000"></a>

          <code class="literal">MYSQL_BIND</code>
        </p><p>
          This structure is used both for statement input (data values
          sent to the server) and output (result values returned from
          the server):
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
              For input, use <code class="literal">MYSQL_BIND</code> structures
              with
              <a class="link" href="connectors-apis.html#mysql-stmt-bind-param" title="27.8.11.4 mysql_stmt_bind_param()"><code class="literal">mysql_stmt_bind_param()</code></a> to
              bind parameter data values to buffers for use by
              <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a>.
            </p></li><li class="listitem"><p>
              For output, use <code class="literal">MYSQL_BIND</code> structures
              with
              <a class="link" href="connectors-apis.html#mysql-stmt-bind-result" title="27.8.11.5 mysql_stmt_bind_result()"><code class="literal">mysql_stmt_bind_result()</code></a>
              to bind buffers to result set columns, for use in fetching
              rows with
              <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a>.
</p></li></ul>
</div>
<p>
          To use a <code class="literal">MYSQL_BIND</code> structure, zero its
          contents to initialize it, then set its members appropriately.
          For example, to declare and initialize an array of three
          <code class="literal">MYSQL_BIND</code> structures, use this code:
        </p><pre data-lang="c" class="programlisting">
MYSQL_BIND bind[3];
memset(bind, 0, sizeof(bind));
</pre><p>
          The <code class="literal">MYSQL_BIND</code> structure contains the
          following members for use by application programs. For several
          of the members, the manner of use depends on whether the
          structure is used for input or output.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
              <code class="literal">enum enum_field_types buffer_type</code>
            </p><p>
              The type of the buffer. This member indicates the data
              type of the C language variable bound to a statement
              parameter or result set column. For input,
              <code class="literal">buffer_type</code> indicates the type of the
              variable containing the value to be sent to the server.
              For output, it indicates the type of the variable into
              which a value received from the server should be stored.
              For permissible <code class="literal">buffer_type</code> values, see
              <a class="xref" href="connectors-apis.html#c-api-prepared-statement-type-codes" title="27.8.9.1 C API Prepared Statement Type Codes">Section 27.8.9.1, “C API Prepared Statement Type Codes”</a>.
            </p></li><li class="listitem"><p>
              <code class="literal">void *buffer</code>
            </p><p>
              A pointer to the buffer to be used for data transfer. This
              is the address of a C language variable.
            </p><p>
              For input, <code class="literal">buffer</code> is a pointer to the
              variable in which you store the data value for a statement
              parameter. When you call
              <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a>,
              MySQL use the value stored in the variable in place of the
              corresponding parameter marker in the statement (specified
              with <code class="literal">?</code> in the statement string).
            </p><p>
              For output, <code class="literal">buffer</code> is a pointer to the
              variable in which to return a result set column value.
              When you call
              <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a>, MySQL
              stores a column value from the current row of the result
              set in this variable. You can access the value when the
              call returns.
            </p><p>
              To minimize the need for MySQL to perform type conversions
              between C language values on the client side and SQL
              values on the server side, use C variables that have types
              similar to those of the corresponding SQL values:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: square; "><li class="listitem"><p>
                  For numeric data types, <code class="literal">buffer</code>
                  should point to a variable of the proper numeric C
                  type. For integer variables (which can be
                  <code class="literal">char</code> for single-byte values or an
                  integer type for larger values), you should also
                  indicate whether the variable has the
                  <code class="literal">unsigned</code> attribute by setting the
                  <code class="literal">is_unsigned</code> member, described
                  later.
                </p></li><li class="listitem"><p>
                  For character (nonbinary) and binary string data
                  types, <code class="literal">buffer</code> should point to a
                  character buffer.
                </p></li><li class="listitem"><p>
                  For date and time data types,
                  <code class="literal">buffer</code> should point to a
                  <code class="literal">MYSQL_TIME</code> structure.
</p></li></ul>
</div>
<p>
              For guidelines about mapping between C types and SQL types
              and notes about type conversions, see
              <a class="xref" href="connectors-apis.html#c-api-prepared-statement-type-codes" title="27.8.9.1 C API Prepared Statement Type Codes">Section 27.8.9.1, “C API Prepared Statement Type Codes”</a>, and
              <a class="xref" href="connectors-apis.html#c-api-prepared-statement-type-conversions" title="27.8.9.2 C API Prepared Statement Type Conversions">Section 27.8.9.2, “C API Prepared Statement Type Conversions”</a>.
            </p></li><li class="listitem"><p>
              <code class="literal">unsigned long buffer_length</code>
            </p><p>
              The actual size of <code class="literal">*buffer</code> in bytes.
              This indicates the maximum amount of data that can be
              stored in the buffer. For character and binary C data, the
              <code class="literal">buffer_length</code> value specifies the
              length of <code class="literal">*buffer</code> when used with
              <a class="link" href="connectors-apis.html#mysql-stmt-bind-param" title="27.8.11.4 mysql_stmt_bind_param()"><code class="literal">mysql_stmt_bind_param()</code></a> to
              specify input values, or the maximum number of output data
              bytes that can be fetched into the buffer when used with
              <a class="link" href="connectors-apis.html#mysql-stmt-bind-result" title="27.8.11.5 mysql_stmt_bind_result()"><code class="literal">mysql_stmt_bind_result()</code></a>.
            </p></li><li class="listitem"><p>
              <code class="literal">unsigned long *length</code>
            </p><p>
              A pointer to an <code class="literal">unsigned long</code> variable
              that indicates the actual number of bytes of data stored
              in <code class="literal">*buffer</code>. <code class="literal">length</code>
              is used for character or binary C data.
            </p><p>
              For input parameter data binding, set
              <code class="literal">*length</code> to indicate the actual length
              of the parameter value stored in
              <code class="literal">*buffer</code>. This is used by
              <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a>.
            </p><p>
              For output value binding, MySQL sets
              <code class="literal">*length</code> when you call
              <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a>. The
              <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a> return
              value determines how to interpret the length:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: square; "><li class="listitem"><p>
                  If the return value is 0, <code class="literal">*length</code>
                  indicates the actual length of the parameter value.
                </p></li><li class="listitem"><p>
                  If the return value is
                  <code class="literal">MYSQL_DATA_TRUNCATED</code>,
                  <code class="literal">*length</code> indicates the nontruncated
                  length of the parameter value. In this case, the
                  minimum of <code class="literal">*length</code> and
                  <code class="literal">buffer_length</code> indicates the actual
                  length of the value.
</p></li></ul>
</div>
<p>
              <code class="literal">length</code> is ignored for numeric and
              temporal data types because the
              <code class="literal">buffer_type</code> value determines the length
              of the data value.
            </p><p>
              If you must determine the length of a returned value
              before fetching it, see
              <a class="xref" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()">Section 27.8.11.11, “mysql_stmt_fetch()”</a>, for some strategies.
            </p></li><li class="listitem"><p>
              <code class="literal">my_bool *is_null</code>
            </p><p>
              This member points to a <code class="literal">my_bool</code>
              variable that is true if a value is
              <code class="literal">NULL</code>, false if it is not
              <code class="literal">NULL</code>. For input, set
              <code class="literal">*is_null</code> to true to indicate that you
              are passing a <code class="literal">NULL</code> value as a statement
              parameter.
            </p><p>
              <code class="literal">is_null</code> is a
              <span class="emphasis"><em>pointer</em></span> to a boolean scalar, not a
              boolean scalar, to provide flexibility in how you specify
              <code class="literal">NULL</code> values:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: square; "><li class="listitem"><p>
                  If your data values are always
                  <code class="literal">NULL</code>, use
                  <code class="literal">MYSQL_TYPE_NULL</code> as the
                  <code class="literal">buffer_type</code> value when you bind the
                  column. The other <code class="literal">MYSQL_BIND</code>
                  members, including <code class="literal">is_null</code>, do not
                  matter.
                </p></li><li class="listitem"><p>
                  If your data values are always <code class="literal">NOT
                  NULL</code>, set <code class="literal">is_null = (my_bool*)
                  0</code>, and set the other members appropriately
                  for the variable you are binding.
                </p></li><li class="listitem"><p>
                  In all other cases, set the other members
                  appropriately and set <code class="literal">is_null</code> to
                  the address of a <code class="literal">my_bool</code> variable.
                  Set that variable's value to true or false
                  appropriately between executions to indicate whether
                  the corresponding data value is
                  <code class="literal">NULL</code> or <code class="literal">NOT
                  NULL</code>, respectively.
</p></li></ul>
</div>
<p>
              For output, when you fetch a row, MySQL sets the value
              pointed to by <code class="literal">is_null</code> to true or false
              according to whether the result set column value returned
              from the statement is or is not <code class="literal">NULL</code>.
            </p></li><li class="listitem"><p>
              <code class="literal">my_bool is_unsigned</code>
            </p><p>
              This member applies for C variables with data types that
              can be <code class="literal">unsigned</code>
              (<code class="literal">char</code>, <code class="literal">short int</code>,
              <code class="literal">int</code>, <code class="literal">long long int</code>).
              Set <code class="literal">is_unsigned</code> to true if the variable
              pointed to by <code class="literal">buffer</code> is
              <code class="literal">unsigned</code> and false otherwise. For
              example, if you bind a <code class="literal">signed char</code>
              variable to <code class="literal">buffer</code>, specify a type code
              of <code class="literal">MYSQL_TYPE_TINY</code> and set
              <code class="literal">is_unsigned</code> to false. If you bind an
              <code class="literal">unsigned char</code> instead, the type code is
              the same but <code class="literal">is_unsigned</code> should be
              true. (For <code class="literal">char</code>, it is not defined
              whether it is signed or unsigned, so it is best to be
              explicit about signedness by using <code class="literal">signed
              char</code> or <code class="literal">unsigned char</code>.)
            </p><p>
              <code class="literal">is_unsigned</code> applies only to the C
              language variable on the client side. It indicates nothing
              about the signedness of the corresponding SQL value on the
              server side. For example, if you use an
              <code class="literal">int</code> variable to supply a value for a
              <code class="literal">BIGINT UNSIGNED</code> column,
              <code class="literal">is_unsigned</code> should be false because
              <code class="literal">int</code> is a signed type. If you use an
              <code class="literal">unsigned int</code> variable to supply a value
              for a <a class="link" href="data-types.html#integer-types" title="11.2.1 Integer Types (Exact Value) - INTEGER, INT, SMALLINT, TINYINT, MEDIUMINT, BIGINT"><code class="literal">BIGINT</code></a> column,
              <code class="literal">is_unsigned</code> should be true because
              <code class="literal">unsigned int</code> is an unsigned type. MySQL
              performs the proper conversion between signed and unsigned
              values in both directions, although a warning occurs if
              truncation results.
            </p></li><li class="listitem"><p>
              <code class="literal">my_bool *error</code>
            </p><p>
              For output, set this member to point to a
              <code class="literal">my_bool</code> variable to have truncation
              information for the parameter stored there after a row
              fetching operation. When truncation reporting is enabled,
              <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a> returns
              <code class="literal">MYSQL_DATA_TRUNCATED</code> and
              <code class="literal">*error</code> is true in the
              <code class="literal">MYSQL_BIND</code> structures for parameters in
              which truncation occurred. Truncation indicates loss of
              sign or significant digits, or that a string was too long
              to fit in a column. Truncation reporting is enabled by
              default, but can be controlled by calling
              <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> with the
              <code class="literal">MYSQL_REPORT_DATA_TRUNCATION</code> option.
</p></li></ul>
</div>
</li><li class="listitem"><p>
          <a class="indexterm" name="idm140710572678224"></a>

          <code class="literal">MYSQL_TIME</code>
        </p><p>
          This structure is used to send and receive
          <a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">DATE</code></a>,
          <a class="link" href="data-types.html#time" title="11.3.2 The TIME Type"><code class="literal">TIME</code></a>,
          <a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">DATETIME</code></a>, and
          <a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">TIMESTAMP</code></a> data directly to and
          from the server. Set the <code class="literal">buffer</code> member to
          point to a <code class="literal">MYSQL_TIME</code> structure, and set
          the <code class="literal">buffer_type</code> member of a
          <code class="literal">MYSQL_BIND</code> structure to one of the temporal
          types (<code class="literal">MYSQL_TYPE_TIME</code>,
          <code class="literal">MYSQL_TYPE_DATE</code>,
          <code class="literal">MYSQL_TYPE_DATETIME</code>,
          <code class="literal">MYSQL_TYPE_TIMESTAMP</code>).
        </p><p>
          The <code class="literal">MYSQL_TIME</code> structure contains the
          members listed in the following table.
</p>
<div class="informaltable">
<table summary="Members of the MYSQL_TIME structure and a description of each member."><col width="40%"><col width="60%"><thead><tr>
              <th scope="col">Member</th>
              <th scope="col">Description</th>
            </tr></thead><tbody><tr>
              <td scope="row"><code class="literal">unsigned int year</code></td>
              <td>The year</td>
            </tr><tr>
              <td scope="row"><code class="literal">unsigned int month</code></td>
              <td>The month of the year</td>
            </tr><tr>
              <td scope="row"><code class="literal">unsigned int day</code></td>
              <td>The day of the month</td>
            </tr><tr>
              <td scope="row"><code class="literal">unsigned int hour</code></td>
              <td>The hour of the day</td>
            </tr><tr>
              <td scope="row"><code class="literal">unsigned int minute</code></td>
              <td>The minute of the hour</td>
            </tr><tr>
              <td scope="row"><code class="literal">unsigned int second</code></td>
              <td>The second of the minute</td>
            </tr><tr>
              <td scope="row"><code class="literal">my_bool neg</code></td>
              <td>A boolean flag indicating whether the time is negative</td>
            </tr><tr>
              <td scope="row"><code class="literal">unsigned long second_part</code></td>
              <td>The fractional part of the second in microseconds</td>
</tr></tbody></table>
</div>
<p>
          Only those parts of a <code class="literal">MYSQL_TIME</code> structure
          that apply to a given type of temporal value are used. The
          <code class="literal">year</code>, <code class="literal">month</code>, and
          <code class="literal">day</code> elements are used for
          <a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">DATE</code></a>,
          <a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">DATETIME</code></a>, and
          <a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">TIMESTAMP</code></a> values. The
          <code class="literal">hour</code>, <code class="literal">minute</code>, and
          <code class="literal">second</code> elements are used for
          <a class="link" href="data-types.html#time" title="11.3.2 The TIME Type"><code class="literal">TIME</code></a>,
          <a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">DATETIME</code></a>, and
          <a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">TIMESTAMP</code></a> values. See
          <a class="xref" href="connectors-apis.html#c-api-prepared-statement-date-handling" title="27.8.17 C API Prepared Statement Handling of Date and Time Values">Section 27.8.17, “C API Prepared Statement Handling of Date and Time Values”</a>.
</p></li></ul>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="c-api-prepared-statement-type-codes"></a>27.8.9.1 C API Prepared Statement Type Codes</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710572620432"></a><a class="indexterm" name="idm140710572618928"></a><p>
        The <code class="literal">buffer_type</code> member of
        <code class="literal">MYSQL_BIND</code> structures indicates the data type
        of the C language variable bound to a statement parameter or
        result set column. For input, <code class="literal">buffer_type</code>
        indicates the type of the variable containing the value to be
        sent to the server. For output, it indicates the type of the
        variable into which a value received from the server should be
        stored.
      </p><p>
        The following table shows the permissible values for the
        <code class="literal">buffer_type</code> member of
        <code class="literal">MYSQL_BIND</code> structures for input values sent
        to the server. The table shows the C variable types that you can
        use, the corresponding type codes, and the SQL data types for
        which the supplied value can be used without conversion. Choose
        the <code class="literal">buffer_type</code> value according to the data
        type of the C language variable that you are binding. For the
        integer types, you should also set the
        <code class="literal">is_unsigned</code> member to indicate whether the
        variable is signed or unsigned.
</p>
<div class="informaltable">
<table summary="C type input variables, corresponding buffer_type values, and the SQL data types for which the supplied value can be used without conversion."><col width="30%"><col width="35%"><col width="35%"><thead><tr>
            <th scope="col">Input Variable C Type</th>
            <th scope="col"><code class="literal">buffer_type</code> Value</th>
            <th scope="col">SQL Type of Destination Value</th>
          </tr></thead><tbody><tr>
            <td scope="row"><code class="literal">signed char</code></td>
            <td><code class="literal">MYSQL_TYPE_TINY</code></td>
            <td><a class="link" href="data-types.html#integer-types" title="11.2.1 Integer Types (Exact Value) - INTEGER, INT, SMALLINT, TINYINT, MEDIUMINT, BIGINT"><code class="literal">TINYINT</code></a></td>
          </tr><tr>
            <td scope="row"><code class="literal">short int</code></td>
            <td><code class="literal">MYSQL_TYPE_SHORT</code></td>
            <td><a class="link" href="data-types.html#integer-types" title="11.2.1 Integer Types (Exact Value) - INTEGER, INT, SMALLINT, TINYINT, MEDIUMINT, BIGINT"><code class="literal">SMALLINT</code></a></td>
          </tr><tr>
            <td scope="row"><code class="literal">int</code></td>
            <td><code class="literal">MYSQL_TYPE_LONG</code></td>
            <td><a class="link" href="data-types.html#integer-types" title="11.2.1 Integer Types (Exact Value) - INTEGER, INT, SMALLINT, TINYINT, MEDIUMINT, BIGINT"><code class="literal">INT</code></a></td>
          </tr><tr>
            <td scope="row"><code class="literal">long long int</code></td>
            <td><code class="literal">MYSQL_TYPE_LONGLONG</code></td>
            <td><a class="link" href="data-types.html#integer-types" title="11.2.1 Integer Types (Exact Value) - INTEGER, INT, SMALLINT, TINYINT, MEDIUMINT, BIGINT"><code class="literal">BIGINT</code></a></td>
          </tr><tr>
            <td scope="row"><code class="literal">float</code></td>
            <td><code class="literal">MYSQL_TYPE_FLOAT</code></td>
            <td><a class="link" href="data-types.html#floating-point-types" title="11.2.3 Floating-Point Types (Approximate Value) - FLOAT, DOUBLE"><code class="literal">FLOAT</code></a></td>
          </tr><tr>
            <td scope="row"><code class="literal">double</code></td>
            <td><code class="literal">MYSQL_TYPE_DOUBLE</code></td>
            <td><a class="link" href="data-types.html#floating-point-types" title="11.2.3 Floating-Point Types (Approximate Value) - FLOAT, DOUBLE"><code class="literal">DOUBLE</code></a></td>
          </tr><tr>
            <td scope="row"><code class="literal">MYSQL_TIME</code></td>
            <td><code class="literal">MYSQL_TYPE_TIME</code></td>
            <td><a class="link" href="data-types.html#time" title="11.3.2 The TIME Type"><code class="literal">TIME</code></a></td>
          </tr><tr>
            <td scope="row"><code class="literal">MYSQL_TIME</code></td>
            <td><code class="literal">MYSQL_TYPE_DATE</code></td>
            <td><a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">DATE</code></a></td>
          </tr><tr>
            <td scope="row"><code class="literal">MYSQL_TIME</code></td>
            <td><code class="literal">MYSQL_TYPE_DATETIME</code></td>
            <td><a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">DATETIME</code></a></td>
          </tr><tr>
            <td scope="row"><code class="literal">MYSQL_TIME</code></td>
            <td><code class="literal">MYSQL_TYPE_TIMESTAMP</code></td>
            <td><a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">TIMESTAMP</code></a></td>
          </tr><tr>
            <td scope="row"><code class="literal">char[]</code></td>
            <td><code class="literal">MYSQL_TYPE_STRING</code></td>
            <td><a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">TEXT</code></a>,
              <a class="link" href="data-types.html#char" title="11.4.1 The CHAR and VARCHAR Types"><code class="literal">CHAR</code></a>,
              <a class="link" href="data-types.html#char" title="11.4.1 The CHAR and VARCHAR Types"><code class="literal">VARCHAR</code></a></td>
          </tr><tr>
            <td scope="row"><code class="literal">char[]</code></td>
            <td><code class="literal">MYSQL_TYPE_BLOB</code></td>
            <td><a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">BLOB</code></a>,
              <a class="link" href="data-types.html#binary-varbinary" title="11.4.2 The BINARY and VARBINARY Types"><code class="literal">BINARY</code></a>,
              <a class="link" href="data-types.html#binary-varbinary" title="11.4.2 The BINARY and VARBINARY Types"><code class="literal">VARBINARY</code></a></td>
          </tr><tr>
            <td scope="row"></td>
            <td><code class="literal">MYSQL_TYPE_NULL</code></td>
            <td><code class="literal">NULL</code></td>
</tr></tbody></table>
</div>
<p>
        Use <code class="literal">MYSQL_TYPE_NULL</code> as indicated in the
        description for the <code class="literal">is_null</code> member in
        <a class="xref" href="connectors-apis.html#c-api-prepared-statement-data-structures" title="27.8.9 C API Prepared Statement Data Structures">Section 27.8.9, “C API Prepared Statement Data Structures”</a>.
      </p><p>
        For input string data, use <code class="literal">MYSQL_TYPE_STRING</code>
        or <code class="literal">MYSQL_TYPE_BLOB</code> depending on whether the
        value is a character (nonbinary) or binary string:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">MYSQL_TYPE_STRING</code> indicates character
            input string data. The value is assumed to be in the
            character set indicated by the
            <a class="link" href="server-administration.html#sysvar_character_set_client"><code class="literal">character_set_client</code></a> system
            variable. If the server stores the value into a column with
            a different character set, it converts the value to that
            character set.
          </p></li><li class="listitem"><p>
            <code class="literal">MYSQL_TYPE_BLOB</code> indicates binary input
            string data. The value is treated as having the
            <code class="literal">binary</code> character set. That is, it is
            treated as a byte string and no conversion occurs.
</p></li></ul>
</div>
<p>
        The following table shows the permissible values for the
        <code class="literal">buffer_type</code> member of
        <code class="literal">MYSQL_BIND</code> structures for output values
        received from the server. The table shows the SQL types of
        received values, the corresponding type codes that such values
        have in result set metadata, and the recommended C language data
        types to bind to the <code class="literal">MYSQL_BIND</code> structure to
        receive the SQL values without conversion. Choose the
        <code class="literal">buffer_type</code> value according to the data type
        of the C language variable that you are binding. For the integer
        types, you should also set the <code class="literal">is_unsigned</code>
        member to indicate whether the variable is signed or unsigned.
</p>
<div class="informaltable">
<table summary="SQL types of received values, corresponding buffer_type values, and recommended C data type output variables."><col width="30%"><col width="35%"><col width="35%"><thead><tr>
            <th scope="col">SQL Type of Received Value</th>
            <th scope="col"><code class="literal">buffer_type</code> Value</th>
            <th scope="col">Output Variable C Type</th>
          </tr></thead><tbody><tr>
            <td scope="row"><a class="link" href="data-types.html#integer-types" title="11.2.1 Integer Types (Exact Value) - INTEGER, INT, SMALLINT, TINYINT, MEDIUMINT, BIGINT"><code class="literal">TINYINT</code></a></td>
            <td><code class="literal">MYSQL_TYPE_TINY</code></td>
            <td><code class="literal">signed char</code></td>
          </tr><tr>
            <td scope="row"><a class="link" href="data-types.html#integer-types" title="11.2.1 Integer Types (Exact Value) - INTEGER, INT, SMALLINT, TINYINT, MEDIUMINT, BIGINT"><code class="literal">SMALLINT</code></a></td>
            <td><code class="literal">MYSQL_TYPE_SHORT</code></td>
            <td><code class="literal">short int</code></td>
          </tr><tr>
            <td scope="row"><a class="link" href="data-types.html#integer-types" title="11.2.1 Integer Types (Exact Value) - INTEGER, INT, SMALLINT, TINYINT, MEDIUMINT, BIGINT"><code class="literal">MEDIUMINT</code></a></td>
            <td><code class="literal">MYSQL_TYPE_INT24</code></td>
            <td><code class="literal">int</code></td>
          </tr><tr>
            <td scope="row"><a class="link" href="data-types.html#integer-types" title="11.2.1 Integer Types (Exact Value) - INTEGER, INT, SMALLINT, TINYINT, MEDIUMINT, BIGINT"><code class="literal">INT</code></a></td>
            <td><code class="literal">MYSQL_TYPE_LONG</code></td>
            <td><code class="literal">int</code></td>
          </tr><tr>
            <td scope="row"><a class="link" href="data-types.html#integer-types" title="11.2.1 Integer Types (Exact Value) - INTEGER, INT, SMALLINT, TINYINT, MEDIUMINT, BIGINT"><code class="literal">BIGINT</code></a></td>
            <td><code class="literal">MYSQL_TYPE_LONGLONG</code></td>
            <td><code class="literal">long long int</code></td>
          </tr><tr>
            <td scope="row"><a class="link" href="data-types.html#floating-point-types" title="11.2.3 Floating-Point Types (Approximate Value) - FLOAT, DOUBLE"><code class="literal">FLOAT</code></a></td>
            <td><code class="literal">MYSQL_TYPE_FLOAT</code></td>
            <td><code class="literal">float</code></td>
          </tr><tr>
            <td scope="row"><a class="link" href="data-types.html#floating-point-types" title="11.2.3 Floating-Point Types (Approximate Value) - FLOAT, DOUBLE"><code class="literal">DOUBLE</code></a></td>
            <td><code class="literal">MYSQL_TYPE_DOUBLE</code></td>
            <td><code class="literal">double</code></td>
          </tr><tr>
            <td scope="row"><a class="link" href="data-types.html#fixed-point-types" title="11.2.2 Fixed-Point Types (Exact Value) - DECIMAL, NUMERIC"><code class="literal">DECIMAL</code></a></td>
            <td><code class="literal">MYSQL_TYPE_NEWDECIMAL</code></td>
            <td><code class="literal">char[]</code></td>
          </tr><tr>
            <td scope="row"><a class="link" href="data-types.html#year" title="11.3.3 The YEAR Type"><code class="literal">YEAR</code></a></td>
            <td><code class="literal">MYSQL_TYPE_SHORT</code></td>
            <td><code class="literal">short int</code></td>
          </tr><tr>
            <td scope="row"><a class="link" href="data-types.html#time" title="11.3.2 The TIME Type"><code class="literal">TIME</code></a></td>
            <td><code class="literal">MYSQL_TYPE_TIME</code></td>
            <td><code class="literal">MYSQL_TIME</code></td>
          </tr><tr>
            <td scope="row"><a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">DATE</code></a></td>
            <td><code class="literal">MYSQL_TYPE_DATE</code></td>
            <td><code class="literal">MYSQL_TIME</code></td>
          </tr><tr>
            <td scope="row"><a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">DATETIME</code></a></td>
            <td><code class="literal">MYSQL_TYPE_DATETIME</code></td>
            <td><code class="literal">MYSQL_TIME</code></td>
          </tr><tr>
            <td scope="row"><a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">TIMESTAMP</code></a></td>
            <td><code class="literal">MYSQL_TYPE_TIMESTAMP</code></td>
            <td><code class="literal">MYSQL_TIME</code></td>
          </tr><tr>
            <td scope="row"><a class="link" href="data-types.html#char" title="11.4.1 The CHAR and VARCHAR Types"><code class="literal">CHAR</code></a>,
              <a class="link" href="data-types.html#binary-varbinary" title="11.4.2 The BINARY and VARBINARY Types"><code class="literal">BINARY</code></a></td>
            <td><code class="literal">MYSQL_TYPE_STRING</code></td>
            <td><code class="literal">char[]</code></td>
          </tr><tr>
            <td scope="row"><a class="link" href="data-types.html#char" title="11.4.1 The CHAR and VARCHAR Types"><code class="literal">VARCHAR</code></a>,
              <a class="link" href="data-types.html#binary-varbinary" title="11.4.2 The BINARY and VARBINARY Types"><code class="literal">VARBINARY</code></a></td>
            <td><code class="literal">MYSQL_TYPE_VAR_STRING</code></td>
            <td><code class="literal">char[]</code></td>
          </tr><tr>
            <td scope="row"><a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">TINYBLOB</code></a>,
              <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">TINYTEXT</code></a></td>
            <td><code class="literal">MYSQL_TYPE_TINY_BLOB</code></td>
            <td><code class="literal">char[]</code></td>
          </tr><tr>
            <td scope="row"><a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">BLOB</code></a>, <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">TEXT</code></a></td>
            <td><code class="literal">MYSQL_TYPE_BLOB</code></td>
            <td><code class="literal">char[]</code></td>
          </tr><tr>
            <td scope="row"><a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">MEDIUMBLOB</code></a>,
              <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">MEDIUMTEXT</code></a></td>
            <td><code class="literal">MYSQL_TYPE_MEDIUM_BLOB</code></td>
            <td><code class="literal">char[]</code></td>
          </tr><tr>
            <td scope="row"><a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">LONGBLOB</code></a>,
              <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">LONGTEXT</code></a></td>
            <td><code class="literal">MYSQL_TYPE_LONG_BLOB</code></td>
            <td><code class="literal">char[]</code></td>
          </tr><tr>
            <td scope="row"><a class="link" href="data-types.html#bit-type" title="11.2.4 Bit-Value Type - BIT"><code class="literal">BIT</code></a></td>
            <td><code class="literal">MYSQL_TYPE_BIT</code></td>
            <td><code class="literal">char[]</code></td>
</tr></tbody></table>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="c-api-prepared-statement-type-conversions"></a>27.8.9.2 C API Prepared Statement Type Conversions</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710572401392"></a><a class="indexterm" name="idm140710572399888"></a><p>
        Prepared statements transmit data between the client and server
        using C language variables on the client side that correspond to
        SQL values on the server side. If there is a mismatch between
        the C variable type on the client side and the corresponding SQL
        value type on the server side, MySQL performs implicit type
        conversions in both directions.
      </p><p>
        MySQL knows the type code for the SQL value on the server side.
        The <code class="literal">buffer_type</code> value in the
        <code class="literal">MYSQL_BIND</code> structure indicates the type code
        of the C variable that holds the value on the client side. The
        two codes together tell MySQL what conversion must be performed,
        if any. Here are some examples:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            If you use <code class="literal">MYSQL_TYPE_LONG</code> with an
            <code class="literal">int</code> variable to pass an integer value to
            the server that is to be stored into a
            <a class="link" href="data-types.html#floating-point-types" title="11.2.3 Floating-Point Types (Approximate Value) - FLOAT, DOUBLE"><code class="literal">FLOAT</code></a> column, MySQL converts
            the value to floating-point format before storing it.
          </p></li><li class="listitem"><p>
            If you fetch an SQL <a class="link" href="data-types.html#integer-types" title="11.2.1 Integer Types (Exact Value) - INTEGER, INT, SMALLINT, TINYINT, MEDIUMINT, BIGINT"><code class="literal">MEDIUMINT</code></a>
            column value, but specify a <code class="literal">buffer_type</code>
            value of <code class="literal">MYSQL_TYPE_LONGLONG</code> and use a C
            variable of type <code class="literal">long long int</code> as the
            destination buffer, MySQL converts the
            <a class="link" href="data-types.html#integer-types" title="11.2.1 Integer Types (Exact Value) - INTEGER, INT, SMALLINT, TINYINT, MEDIUMINT, BIGINT"><code class="literal">MEDIUMINT</code></a> value (which
            requires less than 8 bytes) for storage into the
            <code class="literal">long long int</code> (an 8-byte variable).
          </p></li><li class="listitem"><p>
            If you fetch a numeric column with a value of 255 into a
            <code class="literal">char[4]</code> character array and specify a
            <code class="literal">buffer_type</code> value of
            <code class="literal">MYSQL_TYPE_STRING</code>, the resulting value in
            the array is a 4-byte string <code class="literal">'255\0'</code>.
          </p></li><li class="listitem"><p>
            MySQL returns <a class="link" href="data-types.html#fixed-point-types" title="11.2.2 Fixed-Point Types (Exact Value) - DECIMAL, NUMERIC"><code class="literal">DECIMAL</code></a> values
            as the string representation of the original server-side
            value, which is why the corresponding C type is
            <code class="literal">char[]</code>. For example,
            <code class="literal">12.345</code> is returned to the client as
            <code class="literal">'12.345'</code>. If you specify
            <code class="literal">MYSQL_TYPE_NEWDECIMAL</code> and bind a string
            buffer to the <code class="literal">MYSQL_BIND</code> structure,
            <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a> stores
            the value in the buffer as a string without conversion. If
            instead you specify a numeric variable and type code,
            <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a> converts
            the string-format <a class="link" href="data-types.html#fixed-point-types" title="11.2.2 Fixed-Point Types (Exact Value) - DECIMAL, NUMERIC"><code class="literal">DECIMAL</code></a>
            value to numeric form.
          </p></li><li class="listitem"><p>
            For the <code class="literal">MYSQL_TYPE_BIT</code> type code,
            <a class="link" href="data-types.html#bit-type" title="11.2.4 Bit-Value Type - BIT"><code class="literal">BIT</code></a> values are returned into
            a string buffer, which is why the corresponding C type is
            <code class="literal">char[]</code>. The value represents a bit string
            that requires interpretation on the client side. To return
            the value as a type that is easier to deal with, you can
            cause the value to be cast to integer using either of the
            following types of expressions:
          </p><pre data-lang="c" class="programlisting">
SELECT bit_col + 0 FROM t
SELECT CAST(bit_col AS UNSIGNED) FROM t
</pre><p>
            To retrieve the value, bind an integer variable large enough
            to hold the value and specify the appropriate corresponding
            integer type code.
</p></li></ul>
</div>
<p>
        Before binding variables to the <code class="literal">MYSQL_BIND</code>
        structures that are to be used for fetching column values, you
        can check the type codes for each column of the result set. This
        might be desirable if you want to determine which variable types
        would be best to use to avoid type conversions. To get the type
        codes, call
        <a class="link" href="connectors-apis.html#mysql-stmt-result-metadata" title="27.8.11.23 mysql_stmt_result_metadata()"><code class="literal">mysql_stmt_result_metadata()</code></a>
        after executing the prepared statement with
        <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a>. The
        metadata provides access to the type codes for the result set as
        described in <a class="xref" href="connectors-apis.html#mysql-stmt-result-metadata" title="27.8.11.23 mysql_stmt_result_metadata()">Section 27.8.11.23, “mysql_stmt_result_metadata()”</a>, and
        <a class="xref" href="connectors-apis.html#c-api-data-structures" title="27.8.5 C API Data Structures">Section 27.8.5, “C API Data Structures”</a>.
      </p><p>
        To determine whether output string values in a result set
        returned from the server contain binary or nonbinary data, check
        whether the <code class="literal">charsetnr</code> value of the result set
        metadata is 63 (see <a class="xref" href="connectors-apis.html#c-api-data-structures" title="27.8.5 C API Data Structures">Section 27.8.5, “C API Data Structures”</a>). If
        so, the character set is <code class="literal">binary</code>, which
        indicates binary rather than nonbinary data. This enables you to
        distinguish <a class="link" href="data-types.html#binary-varbinary" title="11.4.2 The BINARY and VARBINARY Types"><code class="literal">BINARY</code></a> from
        <a class="link" href="data-types.html#char" title="11.4.1 The CHAR and VARCHAR Types"><code class="literal">CHAR</code></a>,
        <a class="link" href="data-types.html#binary-varbinary" title="11.4.2 The BINARY and VARBINARY Types"><code class="literal">VARBINARY</code></a> from
        <a class="link" href="data-types.html#char" title="11.4.1 The CHAR and VARCHAR Types"><code class="literal">VARCHAR</code></a>, and the
        <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">BLOB</code></a> types from the
        <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">TEXT</code></a> types.
      </p><p>
        If you cause the <code class="literal">max_length</code> member of the
        <code class="literal">MYSQL_FIELD</code> column metadata structures to be
        set (by calling
        <a class="link" href="connectors-apis.html#mysql-stmt-attr-set" title="27.8.11.3 mysql_stmt_attr_set()"><code class="literal">mysql_stmt_attr_set()</code></a>), be aware
        that the <code class="literal">max_length</code> values for the result set
        indicate the lengths of the longest string representation of the
        result values, not the lengths of the binary representation.
        That is, <code class="literal">max_length</code> does not necessarily
        correspond to the size of the buffers needed to fetch the values
        with the binary protocol used for prepared statements. Choose
        the size of the buffers according to the types of the variables
        into which you fetch the values. For example, a
        <code class="literal">TINYINT</code> column containing the value -128
        might have a <code class="literal">max_length</code> value of 4. But the
        binary representation of any <code class="literal">TINYINT</code> value
        requires only 1 byte for storage, so you can supply a
        <code class="literal">signed char</code> variable in which to store the
        value and set <code class="literal">is_unsigned</code> to indicate that
        values are signed.
      </p><p>
        Metadata changes to tables or views referred to by prepared
        statements are detected and cause automatic repreparation of the
        statement when it is next executed. For more information, see
        <a class="xref" href="optimization.html#statement-caching" title="8.10.4 Caching of Prepared Statements and Stored Programs">Section 8.10.4, “Caching of Prepared Statements and Stored Programs”</a>.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="c-api-prepared-statement-function-overview"></a>27.8.10 C API Prepared Statement Function Overview</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140710572338592"></a><a class="indexterm" name="idm140710572337088"></a><p>
      The following list summarizes the functions available for prepared
      statement processing. For greater detail, see the descriptions in
      <a class="xref" href="connectors-apis.html#c-api-prepared-statement-functions" title="27.8.11 C API Prepared Statement Function Descriptions">Section 27.8.11, “C API Prepared Statement Function Descriptions”</a>.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-affected-rows" title="27.8.11.1 mysql_stmt_affected_rows()"><code class="literal">mysql_stmt_affected_rows()</code></a>:
          Returns the number of rows changed, deleted, or inserted by
          prepared <a class="link" href="sql-syntax.html#update" title="13.2.11 UPDATE Syntax"><code class="literal">UPDATE</code></a>,
          <a class="link" href="sql-syntax.html#delete" title="13.2.2 DELETE Syntax"><code class="literal">DELETE</code></a>, or
          <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT</code></a> statement
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-attr-get" title="27.8.11.2 mysql_stmt_attr_get()"><code class="literal">mysql_stmt_attr_get()</code></a>: Gets
          value of an attribute for a prepared statement
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-attr-set" title="27.8.11.3 mysql_stmt_attr_set()"><code class="literal">mysql_stmt_attr_set()</code></a>: Sets an
          attribute for a prepared statement
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-bind-param" title="27.8.11.4 mysql_stmt_bind_param()"><code class="literal">mysql_stmt_bind_param()</code></a>:
          Associates application data buffers with the parameter markers
          in a prepared SQL statement
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-bind-result" title="27.8.11.5 mysql_stmt_bind_result()"><code class="literal">mysql_stmt_bind_result()</code></a>:
          Associates application data buffers with columns in a result
          set
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-close" title="27.8.11.6 mysql_stmt_close()"><code class="literal">mysql_stmt_close()</code></a>: Frees
          memory used by a prepared statement
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-data-seek" title="27.8.11.7 mysql_stmt_data_seek()"><code class="literal">mysql_stmt_data_seek()</code></a>: Seeks
          to an arbitrary row number in a statement result set
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-errno" title="27.8.11.8 mysql_stmt_errno()"><code class="literal">mysql_stmt_errno()</code></a>: Returns
          the error number for the last statement execution
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-error" title="27.8.11.9 mysql_stmt_error()"><code class="literal">mysql_stmt_error()</code></a>: Returns
          the error message for the last statement execution
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a>: Executes
          a prepared statement
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a>: Fetches
          the next row of data from a result set and returns data for
          all bound columns
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-fetch-column" title="27.8.11.12 mysql_stmt_fetch_column()"><code class="literal">mysql_stmt_fetch_column()</code></a>:
          Fetch data for one column of the current row of a result set
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-field-count" title="27.8.11.13 mysql_stmt_field_count()"><code class="literal">mysql_stmt_field_count()</code></a>:
          Returns the number of result columns for the most recent
          statement
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-free-result" title="27.8.11.14 mysql_stmt_free_result()"><code class="literal">mysql_stmt_free_result()</code></a>: Free
          the resources allocated to a statement handler
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-init" title="27.8.11.15 mysql_stmt_init()"><code class="literal">mysql_stmt_init()</code></a>: Allocates
          memory for a <code class="literal">MYSQL_STMT</code> structure and
          initializes it
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-insert-id" title="27.8.11.16 mysql_stmt_insert_id()"><code class="literal">mysql_stmt_insert_id()</code></a>:
          Returns the ID generated for an
          <code class="literal">AUTO_INCREMENT</code> column by a prepared
          statement
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-next-result" title="27.8.11.17 mysql_stmt_next_result()"><code class="literal">mysql_stmt_next_result()</code></a>:
          Returns/initiates the next result in a multiple-result
          execution
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-num-rows" title="27.8.11.18 mysql_stmt_num_rows()"><code class="literal">mysql_stmt_num_rows()</code></a>: Returns
          the row count from a buffered statement result set
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-param-count" title="27.8.11.19 mysql_stmt_param_count()"><code class="literal">mysql_stmt_param_count()</code></a>:
          Returns the number of parameters in a prepared statement
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-param-metadata" title="27.8.11.20 mysql_stmt_param_metadata()"><code class="literal">mysql_stmt_param_metadata()</code></a>:
          (Return parameter metadata in the form of a result set) This
          function does nothing
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-prepare" title="27.8.11.21 mysql_stmt_prepare()"><code class="literal">mysql_stmt_prepare()</code></a>: Prepares
          an SQL statement string for execution
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-reset" title="27.8.11.22 mysql_stmt_reset()"><code class="literal">mysql_stmt_reset()</code></a>: Resets the
          statement buffers in the server
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-result-metadata" title="27.8.11.23 mysql_stmt_result_metadata()"><code class="literal">mysql_stmt_result_metadata()</code></a>:
          Returns prepared statement metadata in the form of a result
          set
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-row-seek" title="27.8.11.24 mysql_stmt_row_seek()"><code class="literal">mysql_stmt_row_seek()</code></a>: Seeks
          to a row offset in a statement result set, using value
          returned from
          <a class="link" href="connectors-apis.html#mysql-stmt-row-tell" title="27.8.11.25 mysql_stmt_row_tell()"><code class="literal">mysql_stmt_row_tell()</code></a>
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-row-tell" title="27.8.11.25 mysql_stmt_row_tell()"><code class="literal">mysql_stmt_row_tell()</code></a>: Returns
          the statement row cursor position
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-send-long-data" title="27.8.11.26 mysql_stmt_send_long_data()"><code class="literal">mysql_stmt_send_long_data()</code></a>:
          Sends long data in chunks to server
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-sqlstate" title="27.8.11.27 mysql_stmt_sqlstate()"><code class="literal">mysql_stmt_sqlstate()</code></a>: Returns
          the SQLSTATE error code for the last statement execution
        </p></li><li class="listitem"><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-store-result" title="27.8.11.28 mysql_stmt_store_result()"><code class="literal">mysql_stmt_store_result()</code></a>:
          Retrieves a complete result set to the client
</p></li></ul>
</div>
<p>
      Call <a class="link" href="connectors-apis.html#mysql-stmt-init" title="27.8.11.15 mysql_stmt_init()"><code class="literal">mysql_stmt_init()</code></a> to create a
      statement handler, then
      <a class="link" href="connectors-apis.html#mysql-stmt-prepare" title="27.8.11.21 mysql_stmt_prepare()"><code class="literal">mysql_stmt_prepare()</code></a> to prepare
      the statement string,
      <a class="link" href="connectors-apis.html#mysql-stmt-bind-param" title="27.8.11.4 mysql_stmt_bind_param()"><code class="literal">mysql_stmt_bind_param()</code></a> to supply
      the parameter data, and
      <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a> to execute
      the statement. You can repeat the
      <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a> by changing
      parameter values in the respective buffers supplied through
      <a class="link" href="connectors-apis.html#mysql-stmt-bind-param" title="27.8.11.4 mysql_stmt_bind_param()"><code class="literal">mysql_stmt_bind_param()</code></a>.
    </p><p>
      You can send text or binary data in chunks to server using
      <a class="link" href="connectors-apis.html#mysql-stmt-send-long-data" title="27.8.11.26 mysql_stmt_send_long_data()"><code class="literal">mysql_stmt_send_long_data()</code></a>. See
      <a class="xref" href="connectors-apis.html#mysql-stmt-send-long-data" title="27.8.11.26 mysql_stmt_send_long_data()">Section 27.8.11.26, “mysql_stmt_send_long_data()”</a>.
    </p><p>
      If the statement is a <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a> or any
      other statement that produces a result set,
      <a class="link" href="connectors-apis.html#mysql-stmt-prepare" title="27.8.11.21 mysql_stmt_prepare()"><code class="literal">mysql_stmt_prepare()</code></a> also returns
      the result set metadata information in the form of a
      <code class="literal">MYSQL_RES</code> result set through
      <a class="link" href="connectors-apis.html#mysql-stmt-result-metadata" title="27.8.11.23 mysql_stmt_result_metadata()"><code class="literal">mysql_stmt_result_metadata()</code></a>.
    </p><p>
      You can supply the result buffers using
      <a class="link" href="connectors-apis.html#mysql-stmt-bind-result" title="27.8.11.5 mysql_stmt_bind_result()"><code class="literal">mysql_stmt_bind_result()</code></a>, so that
      the <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a>
      automatically returns data to these buffers. This is row-by-row
      fetching.
    </p><p>
      When statement execution has been completed, close the statement
      handler using <a class="link" href="connectors-apis.html#mysql-stmt-close" title="27.8.11.6 mysql_stmt_close()"><code class="literal">mysql_stmt_close()</code></a>
      so that all resources associated with it can be freed. At that
      point the handler becomes invalid and should no longer be used.
    </p><p>
      If you obtained a <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a>
      statement's result set metadata by calling
      <a class="link" href="connectors-apis.html#mysql-stmt-result-metadata" title="27.8.11.23 mysql_stmt_result_metadata()"><code class="literal">mysql_stmt_result_metadata()</code></a>, you
      should also free the metadata using
      <a class="link" href="connectors-apis.html#mysql-free-result" title="27.8.7.25 mysql_free_result()"><code class="literal">mysql_free_result()</code></a>.
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h4 class="title"><a name="c-api-prepared-statement-function-overview-execution-steps"></a>Execution Steps</h4>
</div>
</div>
</div>
<p>
        To prepare and execute a statement, an application follows these
        steps:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
            Create a prepared statement handler with
            <a class="link" href="connectors-apis.html#mysql-stmt-init" title="27.8.11.15 mysql_stmt_init()"><code class="literal">mysql_stmt_init()</code></a>. To
            prepare the statement on the server, call
            <a class="link" href="connectors-apis.html#mysql-stmt-prepare" title="27.8.11.21 mysql_stmt_prepare()"><code class="literal">mysql_stmt_prepare()</code></a> and
            pass it a string containing the SQL statement.
          </p></li><li class="listitem"><p>
            If the statement will produce a result set, call
            <a class="link" href="connectors-apis.html#mysql-stmt-result-metadata" title="27.8.11.23 mysql_stmt_result_metadata()"><code class="literal">mysql_stmt_result_metadata()</code></a>
            to obtain the result set metadata. This metadata is itself
            in the form of result set, albeit a separate one from the
            one that contains the rows returned by the query. The
            metadata result set indicates how many columns are in the
            result and contains information about each column.
          </p></li><li class="listitem"><p>
            Set the values of any parameters using
            <a class="link" href="connectors-apis.html#mysql-stmt-bind-param" title="27.8.11.4 mysql_stmt_bind_param()"><code class="literal">mysql_stmt_bind_param()</code></a>. All
            parameters must be set. Otherwise, statement execution
            returns an error or produces unexpected results.
          </p></li><li class="listitem"><p>
            Call <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a> to
            execute the statement.
          </p></li><li class="listitem"><p>
            If the statement produces a result set, bind the data
            buffers to use for retrieving the row values by calling
            <a class="link" href="connectors-apis.html#mysql-stmt-bind-result" title="27.8.11.5 mysql_stmt_bind_result()"><code class="literal">mysql_stmt_bind_result()</code></a>.
          </p></li><li class="listitem"><p>
            Fetch the data into the buffers row by row by calling
            <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a>
            repeatedly until no more rows are found.
          </p></li><li class="listitem"><p>
            Repeat steps 3 through 6 as necessary, by changing the
            parameter values and re-executing the statement.
</p></li></ol>
</div>
<p>
        When <a class="link" href="connectors-apis.html#mysql-stmt-prepare" title="27.8.11.21 mysql_stmt_prepare()"><code class="literal">mysql_stmt_prepare()</code></a> is
        called, the MySQL client/server protocol performs these actions:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            The server parses the statement and sends the okay status
            back to the client by assigning a statement ID. It also
            sends total number of parameters, a column count, and its
            metadata if it is a result set oriented statement. All
            syntax and semantics of the statement are checked by the
            server during this call.
          </p></li><li class="listitem"><p>
            The client uses this statement ID for the further
            operations, so that the server can identify the statement
            from among its pool of statements.
</p></li></ul>
</div>
<p>
        When <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a> is
        called, the MySQL client/server protocol performs these actions:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            The client uses the statement handler and sends the
            parameter data to the server.
          </p></li><li class="listitem"><p>
            The server identifies the statement using the ID provided by
            the client, replaces the parameter markers with the newly
            supplied data, and executes the statement. If the statement
            produces a result set, the server sends the data back to the
            client. Otherwise, it sends an okay status and the number of
            rows changed, deleted, or inserted.
</p></li></ul>
</div>
<p>
        When <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a> is
        called, the MySQL client/server protocol performs these actions:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            The client reads the data from the current row of the result
            set and places it into the application data buffers by doing
            the necessary conversions. If the application buffer type is
            same as that of the field type returned from the server, the
            conversions are straightforward.
</p></li></ul>
</div>
<p>
        If an error occurs, you can get the statement error number,
        error message, and SQLSTATE code using
        <a class="link" href="connectors-apis.html#mysql-stmt-errno" title="27.8.11.8 mysql_stmt_errno()"><code class="literal">mysql_stmt_errno()</code></a>,
        <a class="link" href="connectors-apis.html#mysql-stmt-error" title="27.8.11.9 mysql_stmt_error()"><code class="literal">mysql_stmt_error()</code></a>, and
        <a class="link" href="connectors-apis.html#mysql-stmt-sqlstate" title="27.8.11.27 mysql_stmt_sqlstate()"><code class="literal">mysql_stmt_sqlstate()</code></a>,
        respectively.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="c-api-prepared-statement-function-overview-prepared-statement-logging"></a>Prepared Statement Logging</h4>

</div>

</div>

</div>
<p>
        For prepared statements that are executed with the
        <a class="link" href="connectors-apis.html#mysql-stmt-prepare" title="27.8.11.21 mysql_stmt_prepare()"><code class="literal">mysql_stmt_prepare()</code></a> and
        <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a> C API
        functions, the server writes <code class="literal">Prepare</code> and
        <code class="literal">Execute</code> lines to the general query log so
        that you can tell when statements are prepared and executed.
      </p><p>
        Suppose that you prepare and execute a statement as follows:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
            Call <a class="link" href="connectors-apis.html#mysql-stmt-prepare" title="27.8.11.21 mysql_stmt_prepare()"><code class="literal">mysql_stmt_prepare()</code></a> to
            prepare the statement string <code class="literal">"SELECT ?"</code>.
          </p></li><li class="listitem"><p>
            Call <a class="link" href="connectors-apis.html#mysql-stmt-bind-param" title="27.8.11.4 mysql_stmt_bind_param()"><code class="literal">mysql_stmt_bind_param()</code></a>
            to bind the value <code class="literal">3</code> to the parameter in
            the prepared statement.
          </p></li><li class="listitem"><p>
            Call <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a> to
            execute the prepared statement.
</p></li></ol>
</div>
<p>
        As a result of the preceding calls, the server writes the
        following lines to the general query log:
      </p><pre data-lang="c" class="programlisting">
Prepare  [1] SELECT ?
Execute  [1] SELECT 3
</pre><p>
        Each <code class="literal">Prepare</code> and <code class="literal">Execute</code>
        line in the log is tagged with a
        <code class="literal">[<em class="replaceable"><code>N</code></em>]</code> statement
        identifier so that you can keep track of which prepared
        statement is being logged. <em class="replaceable"><code>N</code></em> is a
        positive integer. If there are multiple prepared statements
        active simultaneously for the client,
        <em class="replaceable"><code>N</code></em> may be greater than 1. Each
        <code class="literal">Execute</code> lines shows a prepared statement
        after substitution of data values for <code class="literal">?</code>
        parameters.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="c-api-prepared-statement-functions"></a>27.8.11 C API Prepared Statement Function Descriptions</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-affected-rows">27.8.11.1 mysql_stmt_affected_rows()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-attr-get">27.8.11.2 mysql_stmt_attr_get()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-attr-set">27.8.11.3 mysql_stmt_attr_set()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-bind-param">27.8.11.4 mysql_stmt_bind_param()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-bind-result">27.8.11.5 mysql_stmt_bind_result()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-close">27.8.11.6 mysql_stmt_close()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-data-seek">27.8.11.7 mysql_stmt_data_seek()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-errno">27.8.11.8 mysql_stmt_errno()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-error">27.8.11.9 mysql_stmt_error()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-execute">27.8.11.10 mysql_stmt_execute()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-fetch">27.8.11.11 mysql_stmt_fetch()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-fetch-column">27.8.11.12 mysql_stmt_fetch_column()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-field-count">27.8.11.13 mysql_stmt_field_count()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-free-result">27.8.11.14 mysql_stmt_free_result()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-init">27.8.11.15 mysql_stmt_init()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-insert-id">27.8.11.16 mysql_stmt_insert_id()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-next-result">27.8.11.17 mysql_stmt_next_result()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-num-rows">27.8.11.18 mysql_stmt_num_rows()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-param-count">27.8.11.19 mysql_stmt_param_count()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-param-metadata">27.8.11.20 mysql_stmt_param_metadata()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-prepare">27.8.11.21 mysql_stmt_prepare()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-reset">27.8.11.22 mysql_stmt_reset()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-result-metadata">27.8.11.23 mysql_stmt_result_metadata()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-row-seek">27.8.11.24 mysql_stmt_row_seek()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-row-tell">27.8.11.25 mysql_stmt_row_tell()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-send-long-data">27.8.11.26 mysql_stmt_send_long_data()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-sqlstate">27.8.11.27 mysql_stmt_sqlstate()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-stmt-store-result">27.8.11.28 mysql_stmt_store_result()</a></span></dt></dl>
</div>
<p>
      To prepare and execute queries, use the functions described in
      detail in the following sections.
    </p><p>
      All functions that operate with a <code class="literal">MYSQL_STMT</code>
      structure begin with the prefix <code class="literal">mysql_stmt_</code>.
    </p><p>
      To create a <code class="literal">MYSQL_STMT</code> handler, use the
      <a class="link" href="connectors-apis.html#mysql-stmt-init" title="27.8.11.15 mysql_stmt_init()"><code class="literal">mysql_stmt_init()</code></a> function.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-affected-rows"></a>27.8.11.1 mysql_stmt_affected_rows()</h4>
</div>
</div>
</div>
<a class="indexterm" name="idm140710572178608"></a><p>
        <code class="literal">my_ulonglong mysql_stmt_affected_rows(MYSQL_STMT
        *stmt)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-affected-rows-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          <a class="link" href="connectors-apis.html#mysql-stmt-affected-rows" title="27.8.11.1 mysql_stmt_affected_rows()"><code class="literal">mysql_stmt_affected_rows()</code></a> may
          be called immediately after executing a statement with
          <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a>. It is
          like <a class="link" href="connectors-apis.html#mysql-affected-rows" title="27.8.7.1 mysql_affected_rows()"><code class="literal">mysql_affected_rows()</code></a> but
          for prepared statements. For a description of what the
          affected-rows value returned by this function means, See
          <a class="xref" href="connectors-apis.html#mysql-affected-rows" title="27.8.7.1 mysql_affected_rows()">Section 27.8.7.1, “mysql_affected_rows()”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-affected-rows-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-affected-rows-example"></a>Example</h5>

</div>

</div>

</div>
<p>
          See the Example in <a class="xref" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()">Section 27.8.11.10, “mysql_stmt_execute()”</a>.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-attr-get"></a>27.8.11.2 mysql_stmt_attr_get()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710572164960"></a><p>
        <code class="literal">my_bool mysql_stmt_attr_get(MYSQL_STMT *stmt, enum
        enum_stmt_attr_type option, void *arg)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-attr-get-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Can be used to get the current value for a statement
          attribute.
        </p><p>
          The <code class="literal">option</code> argument is the option that you
          want to get; the <code class="literal">arg</code> should point to a
          variable that should contain the option value. If the option
          is an integer, <code class="literal">arg</code> should point to the
          value of the integer.
        </p><p>
          See <a class="xref" href="connectors-apis.html#mysql-stmt-attr-set" title="27.8.11.3 mysql_stmt_attr_set()">Section 27.8.11.3, “mysql_stmt_attr_set()”</a>, for a list of
          options and option types.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-attr-get-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if <code class="literal">option</code> is
          unknown.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-attr-get-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-attr-set"></a>27.8.11.3 mysql_stmt_attr_set()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710572151808"></a><p>
        <code class="literal">my_bool mysql_stmt_attr_set(MYSQL_STMT *stmt, enum
        enum_stmt_attr_type option, const void *arg)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-attr-set-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Can be used to affect behavior for a prepared statement. This
          function may be called multiple times to set several options.
        </p><p>
          The <code class="literal">option</code> argument is the option that you
          want to set. The <code class="literal">arg</code> argument is the value
          for the option. <code class="literal">arg</code> should point to a
          variable that is set to the desired attribute value. The
          variable type is as indicated in the following table.
        </p><p>
          The following table shows the possible
          <code class="literal">option</code> values.
</p>
<div class="informaltable">
<table summary="Lists mysql_stmt_attr_set() option values and the argument type and function of each option."><col width="42%"><col width="20%"><col width="38%"><thead><tr>
              <th scope="col">Option</th>
              <th scope="col">Argument Type</th>
              <th scope="col">Function</th>
            </tr></thead><tbody><tr>
              <td scope="row"><code class="literal">STMT_ATTR_UPDATE_MAX_LENGTH</code></td>
              <td><code class="literal">my_bool *</code></td>
              <td>If set to 1, causes
                <a class="link" href="connectors-apis.html#mysql-stmt-store-result" title="27.8.11.28 mysql_stmt_store_result()"><code class="literal">mysql_stmt_store_result()</code></a>
                to update the metadata
                <code class="literal">MYSQL_FIELD-&gt;max_length</code> value.</td>
            </tr><tr>
              <td scope="row"><code class="literal">STMT_ATTR_CURSOR_TYPE</code></td>
              <td><code class="literal">unsigned long *</code></td>
              <td>Type of cursor to open for statement when
                <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a> is
                invoked. <code class="literal">*arg</code> can be
                <code class="literal">CURSOR_TYPE_NO_CURSOR</code> (the default)
                or <code class="literal">CURSOR_TYPE_READ_ONLY</code>.</td>
            </tr><tr>
              <td scope="row"><code class="literal">STMT_ATTR_PREFETCH_ROWS</code></td>
              <td><code class="literal">unsigned long *</code></td>
              <td>Number of rows to fetch from server at a time when using a cursor.
                <code class="literal">*arg</code> can be in the range from 1 to
                the maximum value of <code class="literal">unsigned long</code>.
                The default is 1.</td>
</tr></tbody></table>
</div>
<p>
          If you use the <code class="literal">STMT_ATTR_CURSOR_TYPE</code> option
          with <code class="literal">CURSOR_TYPE_READ_ONLY</code>, a cursor is
          opened for the statement when you invoke
          <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a>. If there
          is already an open cursor from a previous
          <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a> call, it
          closes the cursor before opening a new one.
          <a class="link" href="connectors-apis.html#mysql-stmt-reset" title="27.8.11.22 mysql_stmt_reset()"><code class="literal">mysql_stmt_reset()</code></a> also closes
          any open cursor before preparing the statement for
          re-execution.
          <a class="link" href="connectors-apis.html#mysql-stmt-free-result" title="27.8.11.14 mysql_stmt_free_result()"><code class="literal">mysql_stmt_free_result()</code></a>
          closes any open cursor.
        </p><p>
          If you open a cursor for a prepared statement,
          <a class="link" href="connectors-apis.html#mysql-stmt-store-result" title="27.8.11.28 mysql_stmt_store_result()"><code class="literal">mysql_stmt_store_result()</code></a> is
          unnecessary, because that function causes the result set to be
          buffered on the client side.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-attr-set-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if <code class="literal">option</code> is
          unknown.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-attr-set-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-attr-set-example"></a>Example</h5>

</div>

</div>

</div>
<p>
          The following example opens a cursor for a prepared statement
          and sets the number of rows to fetch at a time to 5:
        </p><pre data-lang="c" class="programlisting">
MYSQL_STMT *stmt;
int rc;
unsigned long type;
unsigned long prefetch_rows = 5;

stmt = mysql_stmt_init(mysql);
type = (unsigned long) CURSOR_TYPE_READ_ONLY;
rc = mysql_stmt_attr_set(stmt, STMT_ATTR_CURSOR_TYPE, (void*) &amp;type);
/* ... check return value ... */
rc = mysql_stmt_attr_set(stmt, STMT_ATTR_PREFETCH_ROWS,
                         (void*) &amp;prefetch_rows);
/* ... check return value ... */
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-bind-param"></a>27.8.11.4 mysql_stmt_bind_param()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710572099376"></a><p>
        <code class="literal">my_bool mysql_stmt_bind_param(MYSQL_STMT *stmt,
        MYSQL_BIND *bind)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-bind-param-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          <a class="link" href="connectors-apis.html#mysql-stmt-bind-param" title="27.8.11.4 mysql_stmt_bind_param()"><code class="literal">mysql_stmt_bind_param()</code></a> is
          used to bind input data for the parameter markers in the SQL
          statement that was passed to
          <a class="link" href="connectors-apis.html#mysql-stmt-prepare" title="27.8.11.21 mysql_stmt_prepare()"><code class="literal">mysql_stmt_prepare()</code></a>. It uses
          <code class="literal">MYSQL_BIND</code> structures to supply the data.
          <code class="literal">bind</code> is the address of an array of
          <code class="literal">MYSQL_BIND</code> structures. The client library
          expects the array to contain one element for each
          <code class="literal">?</code> parameter marker that is present in the
          query.
        </p><p>
          Suppose that you prepare the following statement:
        </p><pre data-lang="c" class="programlisting">
INSERT INTO mytbl VALUES(?,?,?)
</pre><p>
          When you bind the parameters, the array of
          <code class="literal">MYSQL_BIND</code> structures must contain three
          elements, and can be declared like this:
        </p><pre data-lang="c" class="programlisting">
MYSQL_BIND bind[3];
</pre><p>
          <a class="xref" href="connectors-apis.html#c-api-prepared-statement-data-structures" title="27.8.9 C API Prepared Statement Data Structures">Section 27.8.9, “C API Prepared Statement Data Structures”</a>,
          describes the members of each <code class="literal">MYSQL_BIND</code>
          element and how they should be set to provide input values.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-bind-param-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-bind-param-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unsupported_param_type"><code class="literal">CR_UNSUPPORTED_PARAM_TYPE</code></a>
            </p><p>
              The conversion is not supported. Possibly the
              <code class="literal">buffer_type</code> value is invalid or is not
              one of the supported types.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_out_of_memory"><code class="literal">CR_OUT_OF_MEMORY</code></a>
            </p><p>
              Out of memory.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-bind-param-example"></a>Example</h5>

</div>

</div>

</div>
<p>
          See the Example in <a class="xref" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()">Section 27.8.11.10, “mysql_stmt_execute()”</a>.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-bind-result"></a>27.8.11.5 mysql_stmt_bind_result()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710572069168"></a><p>
        <code class="literal">my_bool mysql_stmt_bind_result(MYSQL_STMT *stmt,
        MYSQL_BIND *bind)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-bind-result-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          <a class="link" href="connectors-apis.html#mysql-stmt-bind-result" title="27.8.11.5 mysql_stmt_bind_result()"><code class="literal">mysql_stmt_bind_result()</code></a> is
          used to associate (that is, bind) output columns in the result
          set to data buffers and length buffers. When
          <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a> is called
          to fetch data, the MySQL client/server protocol places the
          data for the bound columns into the specified buffers.
        </p><p>
          All columns must be bound to buffers prior to calling
          <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a>.
          <code class="literal">bind</code> is the address of an array of
          <code class="literal">MYSQL_BIND</code> structures. The client library
          expects the array to contain one element for each column of
          the result set. If you do not bind columns to
          <code class="literal">MYSQL_BIND</code> structures,
          <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a> simply
          ignores the data fetch. The buffers should be large enough to
          hold the data values, because the protocol does not return
          data values in chunks.
        </p><p>
          A column can be bound or rebound at any time, even after a
          result set has been partially retrieved. The new binding takes
          effect the next time
          <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a> is called.
          Suppose that an application binds the columns in a result set
          and calls <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a>.
          The client/server protocol returns data in the bound buffers.
          Then suppose that the application binds the columns to a
          different set of buffers. The protocol places data into the
          newly bound buffers when the next call to
          <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a> occurs.
        </p><p>
          To bind a column, an application calls
          <a class="link" href="connectors-apis.html#mysql-stmt-bind-result" title="27.8.11.5 mysql_stmt_bind_result()"><code class="literal">mysql_stmt_bind_result()</code></a> and
          passes the type, address, and length of the output buffer into
          which the value should be stored.
          <a class="xref" href="connectors-apis.html#c-api-prepared-statement-data-structures" title="27.8.9 C API Prepared Statement Data Structures">Section 27.8.9, “C API Prepared Statement Data Structures”</a>,
          describes the members of each <code class="literal">MYSQL_BIND</code>
          element and how they should be set to receive output values.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-bind-result-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-bind-result-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unsupported_param_type"><code class="literal">CR_UNSUPPORTED_PARAM_TYPE</code></a>
            </p><p>
              The conversion is not supported. Possibly the
              <code class="literal">buffer_type</code> value is invalid or is not
              one of the supported types.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_out_of_memory"><code class="literal">CR_OUT_OF_MEMORY</code></a>
            </p><p>
              Out of memory.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-bind-result-example"></a>Example</h5>

</div>

</div>

</div>
<p>
          See the Example in <a class="xref" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()">Section 27.8.11.11, “mysql_stmt_fetch()”</a>.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-close"></a>27.8.11.6 mysql_stmt_close()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710572034128"></a><p>
        <code class="literal">my_bool mysql_stmt_close(MYSQL_STMT *stmt)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-close-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Closes the prepared statement.
          <a class="link" href="connectors-apis.html#mysql-stmt-close" title="27.8.11.6 mysql_stmt_close()"><code class="literal">mysql_stmt_close()</code></a> also
          deallocates the statement handler pointed to by
          <code class="literal">stmt</code>, which at that point becomes invalid
          and should no longer be used. For a failed
          <a class="link" href="connectors-apis.html#mysql-stmt-close" title="27.8.11.6 mysql_stmt_close()"><code class="literal">mysql_stmt_close()</code></a> call, do
          not call <a class="link" href="connectors-apis.html#mysql-stmt-error" title="27.8.11.9 mysql_stmt_error()"><code class="literal">mysql_stmt_error()</code></a>,
          or <a class="link" href="connectors-apis.html#mysql-stmt-errno" title="27.8.11.8 mysql_stmt_errno()"><code class="literal">mysql_stmt_errno()</code></a>, or
          <a class="link" href="connectors-apis.html#mysql-stmt-sqlstate" title="27.8.11.27 mysql_stmt_sqlstate()"><code class="literal">mysql_stmt_sqlstate()</code></a> to
          obtain error information because
          <a class="link" href="connectors-apis.html#mysql-stmt-close" title="27.8.11.6 mysql_stmt_close()"><code class="literal">mysql_stmt_close()</code></a> makes the
          statement handler invalid. Call
          <a class="link" href="connectors-apis.html#mysql-error" title="27.8.7.15 mysql_error()"><code class="literal">mysql_error()</code></a>,
          <a class="link" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()"><code class="literal">mysql_errno()</code></a>, or
          <a class="link" href="connectors-apis.html#mysql-sqlstate" title="27.8.7.72 mysql_sqlstate()"><code class="literal">mysql_sqlstate()</code></a> instead.
        </p><p>
          If the current statement has pending or unread results, this
          function cancels them so that the next query can be executed.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-close-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-close-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-close-example"></a>Example</h5>

</div>

</div>

</div>
<p>
          See the Example in <a class="xref" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()">Section 27.8.11.10, “mysql_stmt_execute()”</a>.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-data-seek"></a>27.8.11.7 mysql_stmt_data_seek()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710572005856"></a><p>
        <code class="literal">void mysql_stmt_data_seek(MYSQL_STMT *stmt,
        my_ulonglong offset)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-data-seek-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Seeks to an arbitrary row in a statement result set. The
          <code class="literal">offset</code> value is a row number and should be
          in the range from <code class="literal">0</code> to
          <a class="link" href="connectors-apis.html#mysql-stmt-num-rows" title="27.8.11.18 mysql_stmt_num_rows()"><code class="literal">mysql_stmt_num_rows(stmt)-1</code></a>.
        </p><p>
          This function requires that the statement result set structure
          contains the entire result of the last executed query, so
          <a class="link" href="connectors-apis.html#mysql-stmt-data-seek" title="27.8.11.7 mysql_stmt_data_seek()"><code class="literal">mysql_stmt_data_seek()</code></a> may be
          used only in conjunction with
          <a class="link" href="connectors-apis.html#mysql-stmt-store-result" title="27.8.11.28 mysql_stmt_store_result()"><code class="literal">mysql_stmt_store_result()</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-data-seek-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-data-seek-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-errno"></a>27.8.11.8 mysql_stmt_errno()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571991472"></a><p>
        <code class="literal">unsigned int mysql_stmt_errno(MYSQL_STMT
        *stmt)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-errno-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          For the statement specified by <code class="literal">stmt</code>,
          <a class="link" href="connectors-apis.html#mysql-stmt-errno" title="27.8.11.8 mysql_stmt_errno()"><code class="literal">mysql_stmt_errno()</code></a> returns the
          error code for the most recently invoked statement API
          function that can succeed or fail. A return value of zero
          means that no error occurred. Client error message numbers are
          listed in the MySQL <code class="filename">errmsg.h</code> header file.
          Server error message numbers are listed in
          <code class="filename">mysqld_error.h</code>. Errors also are listed at
          <a class="xref" href="error-handling.html" title="Appendix B Errors, Error Codes, and Common Problems">Appendix B, <i>Errors, Error Codes, and Common Problems</i></a>.
        </p><p>
          If the failed statement API function was
          <a class="link" href="connectors-apis.html#mysql-stmt-close" title="27.8.11.6 mysql_stmt_close()"><code class="literal">mysql_stmt_close()</code></a>, do not
          call or <a class="link" href="connectors-apis.html#mysql-stmt-errno" title="27.8.11.8 mysql_stmt_errno()"><code class="literal">mysql_stmt_errno()</code></a> to
          obtain error information because
          <a class="link" href="connectors-apis.html#mysql-stmt-close" title="27.8.11.6 mysql_stmt_close()"><code class="literal">mysql_stmt_close()</code></a> makes the
          statement handler invalid. Call
          <a class="link" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()"><code class="literal">mysql_errno()</code></a> instead.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-errno-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          An error code value. Zero if no error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-errno-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-error"></a>27.8.11.9 mysql_stmt_error()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571973120"></a><p>
        <code class="literal">const char *mysql_stmt_error(MYSQL_STMT
        *stmt)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-error-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          For the statement specified by <code class="literal">stmt</code>,
          <a class="link" href="connectors-apis.html#mysql-stmt-error" title="27.8.11.9 mysql_stmt_error()"><code class="literal">mysql_stmt_error()</code></a> returns a
          null-terminated string containing the error message for the
          most recently invoked statement API function that can succeed
          or fail. An empty string (<code class="literal">""</code>) is returned
          if no error occurred. Either of these two tests can be used to
          check for an error:
        </p><pre data-lang="c" class="programlisting">
if(*mysql_stmt_errno(stmt))
{
  // an error occurred
}

if (mysql_stmt_error(stmt)[0])
{
  // an error occurred
}
</pre><p>
          If the failed statement API function was
          <a class="link" href="connectors-apis.html#mysql-stmt-close" title="27.8.11.6 mysql_stmt_close()"><code class="literal">mysql_stmt_close()</code></a>, do not
          call <a class="link" href="connectors-apis.html#mysql-stmt-error" title="27.8.11.9 mysql_stmt_error()"><code class="literal">mysql_stmt_error()</code></a> to
          obtain error information because
          <a class="link" href="connectors-apis.html#mysql-stmt-close" title="27.8.11.6 mysql_stmt_close()"><code class="literal">mysql_stmt_close()</code></a> makes the
          statement handler invalid. Call
          <a class="link" href="connectors-apis.html#mysql-error" title="27.8.7.15 mysql_error()"><code class="literal">mysql_error()</code></a> instead.
        </p><p>
          The language of the client error messages may be changed by
          recompiling the MySQL client library. You can choose error
          messages in several different languages.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-error-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          A character string that describes the error. An empty string
          if no error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-error-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-execute"></a>27.8.11.10 mysql_stmt_execute()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571954496"></a><p>
        <code class="literal">int mysql_stmt_execute(MYSQL_STMT *stmt)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-execute-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a> executes
          the prepared query associated with the statement handler. The
          currently bound parameter marker values are sent to server
          during this call, and the server replaces the markers with
          this newly supplied data.
        </p><p>
          Statement processing following
          <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a> depends
          on the type of statement:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              For an <a class="link" href="sql-syntax.html#update" title="13.2.11 UPDATE Syntax"><code class="literal">UPDATE</code></a>,
              <a class="link" href="sql-syntax.html#delete" title="13.2.2 DELETE Syntax"><code class="literal">DELETE</code></a>, or
              <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT</code></a>, the number of
              changed, deleted, or inserted rows can be found by calling
              <a class="link" href="connectors-apis.html#mysql-stmt-affected-rows" title="27.8.11.1 mysql_stmt_affected_rows()"><code class="literal">mysql_stmt_affected_rows()</code></a>.
            </p></li><li class="listitem"><p>
              For a statement such as
              <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a> that generates a
              result set, you must call
              <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a> to
              fetch the data prior to calling any other functions that
              result in query processing. For more information on how to
              fetch the results, refer to
              <a class="xref" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()">Section 27.8.11.11, “mysql_stmt_fetch()”</a>.
            </p><p>
              Do not following invocation of
              <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a> with
              a call to
              <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a> or
              <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a>. Those
              functions are not intended for processing results from
              prepared statements.
</p></li></ul>
</div>
<p>
          For statements that generate a result set, you can request
          that <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a> open
          a cursor for the statement by calling
          <a class="link" href="connectors-apis.html#mysql-stmt-attr-set" title="27.8.11.3 mysql_stmt_attr_set()"><code class="literal">mysql_stmt_attr_set()</code></a> before
          executing the statement. If you execute a statement multiple
          times, <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a>
          closes any open cursor before opening a new one.
        </p><p>
          Metadata changes to tables or views referred to by prepared
          statements are detected and cause automatic repreparation of
          the statement when it is next executed. For more information,
          see <a class="xref" href="optimization.html#statement-caching" title="8.10.4 Caching of Prepared Statements and Stored Programs">Section 8.10.4, “Caching of Prepared Statements and Stored Programs”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-execute-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-execute-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_out_of_memory"><code class="literal">CR_OUT_OF_MEMORY</code></a>
            </p><p>
              Out of memory.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-execute-example"></a>Example</h5>

</div>

</div>

</div>
<p>
          The following example demonstrates how to create and populate
          a table using
          <a class="link" href="connectors-apis.html#mysql-stmt-init" title="27.8.11.15 mysql_stmt_init()"><code class="literal">mysql_stmt_init()</code></a>,
          <a class="link" href="connectors-apis.html#mysql-stmt-prepare" title="27.8.11.21 mysql_stmt_prepare()"><code class="literal">mysql_stmt_prepare()</code></a>,
          <a class="link" href="connectors-apis.html#mysql-stmt-param-count" title="27.8.11.19 mysql_stmt_param_count()"><code class="literal">mysql_stmt_param_count()</code></a>,
          <a class="link" href="connectors-apis.html#mysql-stmt-bind-param" title="27.8.11.4 mysql_stmt_bind_param()"><code class="literal">mysql_stmt_bind_param()</code></a>,
          <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a>, and
          <a class="link" href="connectors-apis.html#mysql-stmt-affected-rows" title="27.8.11.1 mysql_stmt_affected_rows()"><code class="literal">mysql_stmt_affected_rows()</code></a>.
          The <code class="literal">mysql</code> variable is assumed to be a valid
          connection handler. For an example that shows how to retrieve
          data, see <a class="xref" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()">Section 27.8.11.11, “mysql_stmt_fetch()”</a>.
        </p><pre data-lang="c" class="programlisting">
#define STRING_SIZE 50

#define DROP_SAMPLE_TABLE "DROP TABLE IF EXISTS test_table"
#define CREATE_SAMPLE_TABLE "CREATE TABLE test_table(col1 INT,\
                                                 col2 VARCHAR(40),\
                                                 col3 SMALLINT,\
                                                 col4 TIMESTAMP)"
#define INSERT_SAMPLE "INSERT INTO \
                       test_table(col1,col2,col3) \
                       VALUES(?,?,?)"

MYSQL_STMT    *stmt;
MYSQL_BIND    bind[3];
my_ulonglong  affected_rows;
int           param_count;
short         small_data;
int           int_data;
char          str_data[STRING_SIZE];
unsigned long str_length;
my_bool       is_null;

if (mysql_query(mysql, DROP_SAMPLE_TABLE))
{
  fprintf(stderr, " DROP TABLE failed\n");
  fprintf(stderr, " %s\n", mysql_error(mysql));
  exit(0);
}

if (mysql_query(mysql, CREATE_SAMPLE_TABLE))
{
  fprintf(stderr, " CREATE TABLE failed\n");
  fprintf(stderr, " %s\n", mysql_error(mysql));
  exit(0);
}

/* Prepare an INSERT query with 3 parameters */
/* (the TIMESTAMP column is not named; the server */
/*  sets it to the current date and time) */
stmt = mysql_stmt_init(mysql);
if (!stmt)
{
  fprintf(stderr, " mysql_stmt_init(), out of memory\n");
  exit(0);
}
if (mysql_stmt_prepare(stmt, INSERT_SAMPLE, strlen(INSERT_SAMPLE)))
{
  fprintf(stderr, " mysql_stmt_prepare(), INSERT failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}
fprintf(stdout, " prepare, INSERT successful\n");

/* Get the parameter count from the statement */
param_count= mysql_stmt_param_count(stmt);
fprintf(stdout, " total parameters in INSERT: %d\n", param_count);

if (param_count != 3) /* validate parameter count */
{
  fprintf(stderr, " invalid parameter count returned by MySQL\n");
  exit(0);
}

/* Bind the data for all 3 parameters */

memset(bind, 0, sizeof(bind));

/* INTEGER PARAM */
/* This is a number type, so there is no need
   to specify buffer_length */
bind[0].buffer_type= MYSQL_TYPE_LONG;
bind[0].buffer= (char *)&amp;int_data;
bind[0].is_null= 0;
bind[0].length= 0;

/* STRING PARAM */
bind[1].buffer_type= MYSQL_TYPE_STRING;
bind[1].buffer= (char *)str_data;
bind[1].buffer_length= STRING_SIZE;
bind[1].is_null= 0;
bind[1].length= &amp;str_length;

/* SMALLINT PARAM */
bind[2].buffer_type= MYSQL_TYPE_SHORT;
bind[2].buffer= (char *)&amp;small_data;
bind[2].is_null= &amp;is_null;
bind[2].length= 0;

/* Bind the buffers */
if (mysql_stmt_bind_param(stmt, bind))
{
  fprintf(stderr, " mysql_stmt_bind_param() failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

/* Specify the data values for the first row */
int_data= 10;             /* integer */
strncpy(str_data, "MySQL", STRING_SIZE); /* string  */
str_length= strlen(str_data);

/* INSERT SMALLINT data as NULL */
is_null= 1;

/* Execute the INSERT statement - 1*/
if (mysql_stmt_execute(stmt))
{
  fprintf(stderr, " mysql_stmt_execute(), 1 failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

/* Get the number of affected rows */
affected_rows= mysql_stmt_affected_rows(stmt);
fprintf(stdout, " total affected rows(insert 1): %lu\n",
                (unsigned long) affected_rows);

if (affected_rows != 1) /* validate affected rows */
{
  fprintf(stderr, " invalid affected rows by MySQL\n");
  exit(0);
}

/* Specify data values for second row,
   then re-execute the statement */
int_data= 1000;
strncpy(str_data, "
        The most popular Open Source database",
        STRING_SIZE);
str_length= strlen(str_data);
small_data= 1000;         /* smallint */
is_null= 0;               /* reset */

/* Execute the INSERT statement - 2*/
if (mysql_stmt_execute(stmt))
{
  fprintf(stderr, " mysql_stmt_execute, 2 failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

/* Get the total rows affected */
affected_rows= mysql_stmt_affected_rows(stmt);
fprintf(stdout, " total affected rows(insert 2): %lu\n",
                (unsigned long) affected_rows);

if (affected_rows != 1) /* validate affected rows */
{
  fprintf(stderr, " invalid affected rows by MySQL\n");
  exit(0);
}

/* Close the statement */
if (mysql_stmt_close(stmt))
{
  /* mysql_stmt_close() invalidates stmt, so call          */
  /* mysql_error(mysql) rather than mysql_stmt_error(stmt) */
  fprintf(stderr, " failed while closing the statement\n");
  fprintf(stderr, " %s\n", mysql_error(mysql));
  exit(0);
}
</pre>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
            For complete examples on the use of prepared statement
            functions, refer to the file
            <code class="filename">tests/mysql_client_test.c</code>. This file
            can be obtained from a MySQL source distribution or from the
            source repository (see
            <a class="xref" href="installing.html#source-installation" title="2.9 Installing MySQL from Source">Section 2.9, “Installing MySQL from Source”</a>).
</p>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-fetch"></a>27.8.11.11 mysql_stmt_fetch()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571884528"></a><p>
        <code class="literal">int mysql_stmt_fetch(MYSQL_STMT *stmt)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-fetch-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a> returns the
          next row in the result set. It can be called only while the
          result set exists; that is, after a call to
          <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a> for a
          statement such as <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a> that
          produces a result set.
        </p><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a> returns row
          data using the buffers bound by
          <a class="link" href="connectors-apis.html#mysql-stmt-bind-result" title="27.8.11.5 mysql_stmt_bind_result()"><code class="literal">mysql_stmt_bind_result()</code></a>. It
          returns the data in those buffers for all the columns in the
          current row set and the lengths are returned to the
          <code class="literal">length</code> pointer. All columns must be bound
          by the application before it calls
          <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a>.
        </p><p>
          By default, result sets are fetched unbuffered a row at a time
          from the server. To buffer the entire result set on the
          client, call
          <a class="link" href="connectors-apis.html#mysql-stmt-store-result" title="27.8.11.28 mysql_stmt_store_result()"><code class="literal">mysql_stmt_store_result()</code></a>
          after binding the data buffers and before calling
          <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a>.
        </p><p>
          If a fetched data value is a <code class="literal">NULL</code> value,
          the <code class="literal">*is_null</code> value of the corresponding
          <code class="literal">MYSQL_BIND</code> structure contains TRUE (1).
          Otherwise, the data and its length are returned in the
          <code class="literal">*buffer</code> and <code class="literal">*length</code>
          elements based on the buffer type specified by the
          application. Each numeric and temporal type has a fixed
          length, as listed in the following table. The length of the
          string types depends on the length of the actual data value,
          as indicated by <code class="literal">data_length</code>.
</p>
<div class="informaltable">
<table summary="Numeric and temporal MySQL types and the fixed length of each type."><col width="50%"><col width="50%"><thead><tr>
              <th scope="col">Type</th>
              <th scope="col">Length</th>
            </tr></thead><tbody><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_TINY</code></td>
              <td>1</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_SHORT</code></td>
              <td>2</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_LONG</code></td>
              <td>4</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_LONGLONG</code></td>
              <td>8</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_FLOAT</code></td>
              <td>4</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_DOUBLE</code></td>
              <td>8</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_TIME</code></td>
              <td><code class="literal">sizeof(MYSQL_TIME)</code></td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_DATE</code></td>
              <td><code class="literal">sizeof(MYSQL_TIME)</code></td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_DATETIME</code></td>
              <td><code class="literal">sizeof(MYSQL_TIME)</code></td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_STRING</code></td>
              <td><code class="literal">data length</code></td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_TYPE_BLOB</code></td>
              <td><code class="literal">data_length</code></td>
</tr></tbody></table>
</div>
<p>
          In some cases you might want to determine the length of a
          column value before fetching it with
          <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a>. For
          example, the value might be a long string or
          <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">BLOB</code></a> value for which you want
          to know how much space must be allocated. To accomplish this,
          you can use these strategies:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              Before invoking
              <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a> to
              retrieve individual rows, pass
              <code class="literal">STMT_ATTR_UPDATE_MAX_LENGTH</code> to
              <a class="link" href="connectors-apis.html#mysql-stmt-attr-set" title="27.8.11.3 mysql_stmt_attr_set()"><code class="literal">mysql_stmt_attr_set()</code></a>,
              then invoke
              <a class="link" href="connectors-apis.html#mysql-stmt-store-result" title="27.8.11.28 mysql_stmt_store_result()"><code class="literal">mysql_stmt_store_result()</code></a>
              to buffer the entire result on the client side. Setting
              the <code class="literal">STMT_ATTR_UPDATE_MAX_LENGTH</code>
              attribute causes the maximal length of column values to be
              indicated by the <code class="literal">max_length</code> member of
              the result set metadata returned by
              <a class="link" href="connectors-apis.html#mysql-stmt-result-metadata" title="27.8.11.23 mysql_stmt_result_metadata()"><code class="literal">mysql_stmt_result_metadata()</code></a>.
            </p></li><li class="listitem"><p>
              Invoke <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a>
              with a zero-length buffer for the column in question and a
              pointer in which the real length can be stored. Then use
              the real length with
              <a class="link" href="connectors-apis.html#mysql-stmt-fetch-column" title="27.8.11.12 mysql_stmt_fetch_column()"><code class="literal">mysql_stmt_fetch_column()</code></a>.
            </p><pre data-lang="c" class="programlisting">
real_length= 0;

bind[0].buffer= 0;
bind[0].buffer_length= 0;
bind[0].length= &amp;real_length
mysql_stmt_bind_result(stmt, bind);

mysql_stmt_fetch(stmt);
if (real_length &gt; 0)
{
  data= malloc(real_length);
  bind[0].buffer= data;
  bind[0].buffer_length= real_length;
  mysql_stmt_fetch_column(stmt, bind, 0, 0);
}
</pre></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-fetch-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<div class="informaltable">
<table summary="Return values for mysql_stmt_fetch() and a description of each value."><col width="35%"><col width="65%"><thead><tr>
              <th scope="col">Return Value</th>
              <th scope="col">Description</th>
            </tr></thead><tbody><tr>
              <td scope="row">0</td>
              <td>Successful, the data has been fetched to application data buffers.</td>
            </tr><tr>
              <td scope="row">1</td>
              <td>Error occurred. Error code and message can be obtained by calling
                <a class="link" href="connectors-apis.html#mysql-stmt-errno" title="27.8.11.8 mysql_stmt_errno()"><code class="literal">mysql_stmt_errno()</code></a> and
                <a class="link" href="connectors-apis.html#mysql-stmt-error" title="27.8.11.9 mysql_stmt_error()"><code class="literal">mysql_stmt_error()</code></a>.</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_NO_DATA</code></td>
              <td>No more rows/data exists</td>
            </tr><tr>
              <td scope="row"><code class="literal">MYSQL_DATA_TRUNCATED</code></td>
              <td>Data truncation occurred</td>
</tr></tbody></table>
</div>
<p>
          <code class="literal">MYSQL_DATA_TRUNCATED</code> is returned when
          truncation reporting is enabled. To determine which column
          values were truncated when this value is returned, check the
          <code class="literal">error</code> members of the
          <code class="literal">MYSQL_BIND</code> structures used for fetching
          values. Truncation reporting is enabled by default, but can be
          controlled by calling
          <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> with the
          <code class="literal">MYSQL_REPORT_DATA_TRUNCATION</code> option.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-fetch-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_out_of_memory"><code class="literal">CR_OUT_OF_MEMORY</code></a>
            </p><p>
              Out of memory.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unsupported_param_type"><code class="literal">CR_UNSUPPORTED_PARAM_TYPE</code></a>
            </p><p>
              The buffer type is <code class="literal">MYSQL_TYPE_DATE</code>,
              <code class="literal">MYSQL_TYPE_TIME</code>,
              <code class="literal">MYSQL_TYPE_DATETIME</code>, or
              <code class="literal">MYSQL_TYPE_TIMESTAMP</code>, but the data type
              is not <a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">DATE</code></a>,
              <a class="link" href="data-types.html#time" title="11.3.2 The TIME Type"><code class="literal">TIME</code></a>,
              <a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">DATETIME</code></a>, or
              <a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">TIMESTAMP</code></a>.
            </p></li><li class="listitem"><p>
              All other unsupported conversion errors are returned from
              <a class="link" href="connectors-apis.html#mysql-stmt-bind-result" title="27.8.11.5 mysql_stmt_bind_result()"><code class="literal">mysql_stmt_bind_result()</code></a>.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-fetch-example"></a>Example</h5>

</div>

</div>

</div>
<p>
          The following example demonstrates how to fetch data from a
          table using
          <a class="link" href="connectors-apis.html#mysql-stmt-result-metadata" title="27.8.11.23 mysql_stmt_result_metadata()"><code class="literal">mysql_stmt_result_metadata()</code></a>,
          <a class="link" href="connectors-apis.html#mysql-stmt-bind-result" title="27.8.11.5 mysql_stmt_bind_result()"><code class="literal">mysql_stmt_bind_result()</code></a>, and
          <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a>. (This
          example expects to retrieve the two rows inserted by the
          example shown in <a class="xref" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()">Section 27.8.11.10, “mysql_stmt_execute()”</a>.) The
          <code class="literal">mysql</code> variable is assumed to be a valid
          connection handler.
        </p><pre data-lang="c" class="programlisting">
#define STRING_SIZE 50

#define SELECT_SAMPLE "SELECT col1, col2, col3, col4 \
                       FROM test_table"

MYSQL_STMT    *stmt;
MYSQL_BIND    bind[4];
MYSQL_RES     *prepare_meta_result;
MYSQL_TIME    ts;
unsigned long length[4];
int           param_count, column_count, row_count;
short         small_data;
int           int_data;
char          str_data[STRING_SIZE];
my_bool       is_null[4];
my_bool       error[4];

/* Prepare a SELECT query to fetch data from test_table */
stmt = mysql_stmt_init(mysql);
if (!stmt)
{
  fprintf(stderr, " mysql_stmt_init(), out of memory\n");
  exit(0);
}
if (mysql_stmt_prepare(stmt, SELECT_SAMPLE, strlen(SELECT_SAMPLE)))
{
  fprintf(stderr, " mysql_stmt_prepare(), SELECT failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}
fprintf(stdout, " prepare, SELECT successful\n");

/* Get the parameter count from the statement */
param_count= mysql_stmt_param_count(stmt);
fprintf(stdout, " total parameters in SELECT: %d\n", param_count);

if (param_count != 0) /* validate parameter count */
{
  fprintf(stderr, " invalid parameter count returned by MySQL\n");
  exit(0);
}

/* Fetch result set meta information */
prepare_meta_result = mysql_stmt_result_metadata(stmt);
if (!prepare_meta_result)
{
  fprintf(stderr,
         " mysql_stmt_result_metadata(), \
           returned no meta information\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

/* Get total columns in the query */
column_count= mysql_num_fields(prepare_meta_result);
fprintf(stdout,
        " total columns in SELECT statement: %d\n",
        column_count);

if (column_count != 4) /* validate column count */
{
  fprintf(stderr, " invalid column count returned by MySQL\n");
  exit(0);
}

/* Execute the SELECT query */
if (mysql_stmt_execute(stmt))
{
  fprintf(stderr, " mysql_stmt_execute(), failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

/* Bind the result buffers for all 4 columns before fetching them */

memset(bind, 0, sizeof(bind));

/* INTEGER COLUMN */
bind[0].buffer_type= MYSQL_TYPE_LONG;
bind[0].buffer= (char *)&amp;int_data;
bind[0].is_null= &amp;is_null[0];
bind[0].length= &amp;length[0];
bind[0].error= &amp;error[0];

/* STRING COLUMN */
bind[1].buffer_type= MYSQL_TYPE_STRING;
bind[1].buffer= (char *)str_data;
bind[1].buffer_length= STRING_SIZE;
bind[1].is_null= &amp;is_null[1];
bind[1].length= &amp;length[1];
bind[1].error= &amp;error[1];

/* SMALLINT COLUMN */
bind[2].buffer_type= MYSQL_TYPE_SHORT;
bind[2].buffer= (char *)&amp;small_data;
bind[2].is_null= &amp;is_null[2];
bind[2].length= &amp;length[2];
bind[2].error= &amp;error[2];

/* TIMESTAMP COLUMN */
bind[3].buffer_type= MYSQL_TYPE_TIMESTAMP;
bind[3].buffer= (char *)&amp;ts;
bind[3].is_null= &amp;is_null[3];
bind[3].length= &amp;length[3];
bind[3].error= &amp;error[3];

/* Bind the result buffers */
if (mysql_stmt_bind_result(stmt, bind))
{
  fprintf(stderr, " mysql_stmt_bind_result() failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

/* Now buffer all results to client (optional step) */
if (mysql_stmt_store_result(stmt))
{
  fprintf(stderr, " mysql_stmt_store_result() failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

/* Fetch all rows */
row_count= 0;
fprintf(stdout, "Fetching results ...\n");
while (!mysql_stmt_fetch(stmt))
{
  row_count++;
  fprintf(stdout, "  row %d\n", row_count);

  /* column 1 */
  fprintf(stdout, "   column1 (integer)  : ");
  if (is_null[0])
    fprintf(stdout, " NULL\n");
  else
    fprintf(stdout, " %d(%ld)\n", int_data, length[0]);

  /* column 2 */
  fprintf(stdout, "   column2 (string)   : ");
  if (is_null[1])
    fprintf(stdout, " NULL\n");
  else
    fprintf(stdout, " %s(%ld)\n", str_data, length[1]);

  /* column 3 */
  fprintf(stdout, "   column3 (smallint) : ");
  if (is_null[2])
    fprintf(stdout, " NULL\n");
  else
    fprintf(stdout, " %d(%ld)\n", small_data, length[2]);

  /* column 4 */
  fprintf(stdout, "   column4 (timestamp): ");
  if (is_null[3])
    fprintf(stdout, " NULL\n");
  else
    fprintf(stdout, " %04d-%02d-%02d %02d:%02d:%02d (%ld)\n",
                     ts.year, ts.month, ts.day,
                     ts.hour, ts.minute, ts.second,
                     length[3]);
  fprintf(stdout, "\n");
}

/* Validate rows fetched */
fprintf(stdout, " total rows fetched: %d\n", row_count);
if (row_count != 2)
{
  fprintf(stderr, " MySQL failed to return all rows\n");
  exit(0);
}

/* Free the prepared result metadata */
mysql_free_result(prepare_meta_result);


/* Close the statement */
if (mysql_stmt_close(stmt))
{
  /* mysql_stmt_close() invalidates stmt, so call          */
  /* mysql_error(mysql) rather than mysql_stmt_error(stmt) */
  fprintf(stderr, " failed while closing the statement\n");
  fprintf(stderr, " %s\n", mysql_error(mysql));
  exit(0);
}
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-fetch-column"></a>27.8.11.12 mysql_stmt_fetch_column()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571736736"></a><p>
        <code class="literal">int mysql_stmt_fetch_column(MYSQL_STMT *stmt,
        MYSQL_BIND *bind, unsigned int column, unsigned long
        offset)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-fetch-column-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Fetches one column from the current result set row.
          <code class="literal">bind</code> provides the buffer where data should
          be placed. It should be set up the same way as for
          <a class="link" href="connectors-apis.html#mysql-stmt-bind-result" title="27.8.11.5 mysql_stmt_bind_result()"><code class="literal">mysql_stmt_bind_result()</code></a>.
          <code class="literal">column</code> indicates which column to fetch. The
          first column is numbered 0. <code class="literal">offset</code> is the
          offset within the data value at which to begin retrieving
          data. This can be used for fetching the data value in pieces.
          The beginning of the value is offset 0.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-fetch-column-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-fetch-column-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_invalid_parameter_no"><code class="literal">CR_INVALID_PARAMETER_NO</code></a>
            </p><p>
              Invalid column number.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_no_data"><code class="literal">CR_NO_DATA</code></a>
            </p><p>
              The end of the result set has already been reached.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-field-count"></a>27.8.11.13 mysql_stmt_field_count()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571719376"></a><p>
        <code class="literal">unsigned int mysql_stmt_field_count(MYSQL_STMT
        *stmt)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-field-count-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns the number of columns for the most recent statement
          for the statement handler. This value is zero for statements
          such as <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT</code></a> or
          <a class="link" href="sql-syntax.html#delete" title="13.2.2 DELETE Syntax"><code class="literal">DELETE</code></a> that do not produce
          result sets.
        </p><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-field-count" title="27.8.11.13 mysql_stmt_field_count()"><code class="literal">mysql_stmt_field_count()</code></a> can
          be called after you have prepared a statement by invoking
          <a class="link" href="connectors-apis.html#mysql-stmt-prepare" title="27.8.11.21 mysql_stmt_prepare()"><code class="literal">mysql_stmt_prepare()</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-field-count-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          An unsigned integer representing the number of columns in a
          result set.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-field-count-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-free-result"></a>27.8.11.14 mysql_stmt_free_result()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571705200"></a><p>
        <code class="literal">my_bool mysql_stmt_free_result(MYSQL_STMT
        *stmt)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-free-result-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Releases memory associated with the result set produced by
          execution of the prepared statement. If there is a cursor open
          for the statement,
          <a class="link" href="connectors-apis.html#mysql-stmt-free-result" title="27.8.11.14 mysql_stmt_free_result()"><code class="literal">mysql_stmt_free_result()</code></a>
          closes it.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-free-result-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-init"></a>27.8.11.15 mysql_stmt_init()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571697008"></a><p>
        <code class="literal">MYSQL_STMT *mysql_stmt_init(MYSQL *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-init-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Creates and returns a <code class="literal">MYSQL_STMT</code> handler.
          The handler should be freed with
          <a class="link" href="connectors-apis.html#mysql-stmt-close" title="27.8.11.6 mysql_stmt_close()"><code class="literal">mysql_stmt_close()</code></a>, at which
          point the handler becomes invalid and should no longer be
          used.
        </p><p>
          See also
          <a class="xref" href="connectors-apis.html#c-api-prepared-statement-data-structures" title="27.8.9 C API Prepared Statement Data Structures">Section 27.8.9, “C API Prepared Statement Data Structures”</a>,
          for more information.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-init-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          A pointer to a <code class="literal">MYSQL_STMT</code> structure in case
          of success. <code class="literal">NULL</code> if out of memory.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-init-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_out_of_memory"><code class="literal">CR_OUT_OF_MEMORY</code></a>
            </p><p>
              Out of memory.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-insert-id"></a>27.8.11.16 mysql_stmt_insert_id()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571681376"></a><p>
        <code class="literal">my_ulonglong mysql_stmt_insert_id(MYSQL_STMT
        *stmt)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-insert-id-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns the value generated for an
          <code class="literal">AUTO_INCREMENT</code> column by the prepared
          <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT</code></a> or
          <a class="link" href="sql-syntax.html#update" title="13.2.11 UPDATE Syntax"><code class="literal">UPDATE</code></a> statement. Use this
          function after you have executed a prepared
          <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT</code></a> statement on a table
          which contains an <code class="literal">AUTO_INCREMENT</code> field.
        </p><p>
          See <a class="xref" href="connectors-apis.html#mysql-insert-id" title="27.8.7.38 mysql_insert_id()">Section 27.8.7.38, “mysql_insert_id()”</a>, for more information.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-insert-id-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Value for <code class="literal">AUTO_INCREMENT</code> column which was
          automatically generated or explicitly set during execution of
          prepared statement, or value generated by
          <a class="link" href="functions.html#function_last-insert-id"><code class="literal">LAST_INSERT_ID(<em class="replaceable"><code>expr</code></em>)</code></a>
          function. Return value is undefined if statement does not set
          <code class="literal">AUTO_INCREMENT</code> value.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-insert-id-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-next-result"></a>27.8.11.17 mysql_stmt_next_result()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571662288"></a><p>
        <code class="literal">int mysql_stmt_next_result(MYSQL_STMT *mysql)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-next-result-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          This function is used when you use prepared
          <a class="link" href="sql-syntax.html#call" title="13.2.1 CALL Syntax"><code class="literal">CALL</code></a> statements to execute
          stored procedures, which can return multiple result sets. Use
          a loop that calls
          <a class="link" href="connectors-apis.html#mysql-stmt-next-result" title="27.8.11.17 mysql_stmt_next_result()"><code class="literal">mysql_stmt_next_result()</code></a> to
          determine whether there are more results. If a procedure has
          <code class="literal">OUT</code> or <code class="literal">INOUT</code> parameters,
          their values will be returned as a single-row result set
          following any other result sets. The values will appear in the
          order in which they are declared in the procedure parameter
          list.
        </p><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-next-result" title="27.8.11.17 mysql_stmt_next_result()"><code class="literal">mysql_stmt_next_result()</code></a>
          returns a status to indicate whether more results exist. If
          <a class="link" href="connectors-apis.html#mysql-stmt-next-result" title="27.8.11.17 mysql_stmt_next_result()"><code class="literal">mysql_stmt_next_result()</code></a>
          returns an error, there are no more results.
        </p><p>
          Before each call to
          <a class="link" href="connectors-apis.html#mysql-stmt-next-result" title="27.8.11.17 mysql_stmt_next_result()"><code class="literal">mysql_stmt_next_result()</code></a>, you
          must call
          <a class="link" href="connectors-apis.html#mysql-stmt-free-result" title="27.8.11.14 mysql_stmt_free_result()"><code class="literal">mysql_stmt_free_result()</code></a> for
          the current result if it produced a result set (rather than
          just a result status).
        </p><p>
          After calling
          <a class="link" href="connectors-apis.html#mysql-stmt-next-result" title="27.8.11.17 mysql_stmt_next_result()"><code class="literal">mysql_stmt_next_result()</code></a> the
          state of the connection is as if you had called
          <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a>. This
          means that you can call
          <a class="link" href="connectors-apis.html#mysql-stmt-bind-result" title="27.8.11.5 mysql_stmt_bind_result()"><code class="literal">mysql_stmt_bind_result()</code></a>,
          <a class="link" href="connectors-apis.html#mysql-stmt-affected-rows" title="27.8.11.1 mysql_stmt_affected_rows()"><code class="literal">mysql_stmt_affected_rows()</code></a>,
          and so forth.
        </p><p>
          It is also possible to test whether there are more results by
          calling <a class="link" href="connectors-apis.html#mysql-more-results" title="27.8.7.46 mysql_more_results()"><code class="literal">mysql_more_results()</code></a>.
          However, this function does not change the connection state,
          so if it returns true, you must still call
          <a class="link" href="connectors-apis.html#mysql-stmt-next-result" title="27.8.11.17 mysql_stmt_next_result()"><code class="literal">mysql_stmt_next_result()</code></a> to
          advance to the next result.
        </p><p>
          For an example that shows how to use
          <a class="link" href="connectors-apis.html#mysql-stmt-next-result" title="27.8.11.17 mysql_stmt_next_result()"><code class="literal">mysql_stmt_next_result()</code></a>, see
          <a class="xref" href="connectors-apis.html#c-api-prepared-call-statements" title="27.8.18 C API Prepared CALL Statement Support">Section 27.8.18, “C API Prepared CALL Statement Support”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-next-result-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<div class="informaltable">
<table summary="Return values for mysql_stmt_next_result() and a description of each value."><col width="35%"><col width="65%"><thead><tr>
              <th scope="col">Return Value</th>
              <th scope="col">Description</th>
            </tr></thead><tbody><tr>
              <td scope="row">0</td>
              <td>Successful and there are more results</td>
            </tr><tr>
              <td scope="row">-1</td>
              <td>Successful and there are no more results</td>
            </tr><tr>
              <td scope="row">&gt;0</td>
              <td>An error occurred</td>
</tr></tbody></table>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-next-result-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-num-rows"></a>27.8.11.18 mysql_stmt_num_rows()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571610208"></a><p>
        <code class="literal">my_ulonglong mysql_stmt_num_rows(MYSQL_STMT
        *stmt)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-num-rows-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns the number of rows in the result set.
        </p><p>
          The use of
          <a class="link" href="connectors-apis.html#mysql-stmt-num-rows" title="27.8.11.18 mysql_stmt_num_rows()"><code class="literal">mysql_stmt_num_rows()</code></a> depends
          on whether you used
          <a class="link" href="connectors-apis.html#mysql-stmt-store-result" title="27.8.11.28 mysql_stmt_store_result()"><code class="literal">mysql_stmt_store_result()</code></a> to
          buffer the entire result set in the statement handler. If you
          use <a class="link" href="connectors-apis.html#mysql-stmt-store-result" title="27.8.11.28 mysql_stmt_store_result()"><code class="literal">mysql_stmt_store_result()</code></a>,
          <a class="link" href="connectors-apis.html#mysql-stmt-num-rows" title="27.8.11.18 mysql_stmt_num_rows()"><code class="literal">mysql_stmt_num_rows()</code></a> may be
          called immediately. Otherwise, the row count is unavailable
          unless you count the rows as you fetch them.
        </p><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-num-rows" title="27.8.11.18 mysql_stmt_num_rows()"><code class="literal">mysql_stmt_num_rows()</code></a> is
          intended for use with statements that return a result set,
          such as <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a>. For statements
          such as <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT</code></a>,
          <a class="link" href="sql-syntax.html#update" title="13.2.11 UPDATE Syntax"><code class="literal">UPDATE</code></a>, or
          <a class="link" href="sql-syntax.html#delete" title="13.2.2 DELETE Syntax"><code class="literal">DELETE</code></a>, the number of affected
          rows can be obtained with
          <a class="link" href="connectors-apis.html#mysql-stmt-affected-rows" title="27.8.11.1 mysql_stmt_affected_rows()"><code class="literal">mysql_stmt_affected_rows()</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-num-rows-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          The number of rows in the result set.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-num-rows-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-param-count"></a>27.8.11.19 mysql_stmt_param_count()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571587968"></a><p>
        <code class="literal">unsigned long mysql_stmt_param_count(MYSQL_STMT
        *stmt)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-param-count-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns the number of parameter markers present in the
          prepared statement.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-param-count-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          An unsigned long integer representing the number of parameters
          in a statement.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-param-count-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-param-count-example"></a>Example</h5>

</div>

</div>

</div>
<p>
          See the Example in <a class="xref" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()">Section 27.8.11.10, “mysql_stmt_execute()”</a>.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-param-metadata"></a>27.8.11.20 mysql_stmt_param_metadata()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571576960"></a><p>
        <code class="literal">MYSQL_RES *mysql_stmt_param_metadata(MYSQL_STMT
        *stmt)</code>
      </p><p>
        This function currently does nothing.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-prepare"></a>27.8.11.21 mysql_stmt_prepare()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571573136"></a><p>
        <code class="literal">int mysql_stmt_prepare(MYSQL_STMT *stmt, const char
        *stmt_str, unsigned long length)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-prepare-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Given the statement handler returned by
          <a class="link" href="connectors-apis.html#mysql-stmt-init" title="27.8.11.15 mysql_stmt_init()"><code class="literal">mysql_stmt_init()</code></a>, prepares
          the SQL statement pointed to by the string
          <code class="literal">stmt_str</code> and returns a status value. The
          string length should be given by the <code class="literal">length</code>
          argument. The string must consist of a single SQL statement.
          You should not add a terminating semicolon
          (<code class="literal">;</code>) or <code class="literal">\g</code> to the
          statement.
        </p><p>
          The application can include one or more parameter markers in
          the SQL statement by embedding question mark
          (<code class="literal">?</code>) characters into the SQL string at the
          appropriate positions.
        </p><p>
          The markers are legal only in certain places in SQL
          statements. For example, they are permitted in the
          <code class="literal">VALUES()</code> list of an
          <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT</code></a> statement (to specify
          column values for a row), or in a comparison with a column in
          a <code class="literal">WHERE</code> clause to specify a comparison
          value. However, they are not permitted for identifiers (such
          as table or column names), or to specify both operands of a
          binary operator such as the <code class="literal">=</code> equal sign.
          The latter restriction is necessary because it would be
          impossible to determine the parameter type. In general,
          parameters are legal only in Data Manipulation Language (DML)
          statements, and not in Data Definition Language (DDL)
          statements.
        </p><p>
          The parameter markers must be bound to application variables
          using <a class="link" href="connectors-apis.html#mysql-stmt-bind-param" title="27.8.11.4 mysql_stmt_bind_param()"><code class="literal">mysql_stmt_bind_param()</code></a>
          before executing the statement.
        </p><p>
          Metadata changes to tables or views referred to by prepared
          statements are detected and cause automatic repreparation of
          the statement when it is next executed. For more information,
          see <a class="xref" href="optimization.html#statement-caching" title="8.10.4 Caching of Prepared Statements and Stored Programs">Section 8.10.4, “Caching of Prepared Statements and Stored Programs”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-prepare-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-prepare-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_out_of_memory"><code class="literal">CR_OUT_OF_MEMORY</code></a>
            </p><p>
              Out of memory.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>
<p>
          If the prepare operation was unsuccessful (that is,
          <a class="link" href="connectors-apis.html#mysql-stmt-prepare" title="27.8.11.21 mysql_stmt_prepare()"><code class="literal">mysql_stmt_prepare()</code></a> returns
          nonzero), the error message can be obtained by calling
          <a class="link" href="connectors-apis.html#mysql-stmt-error" title="27.8.11.9 mysql_stmt_error()"><code class="literal">mysql_stmt_error()</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-prepare-example"></a>Example</h5>

</div>

</div>

</div>
<p>
          See the Example in <a class="xref" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()">Section 27.8.11.10, “mysql_stmt_execute()”</a>.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-reset"></a>27.8.11.22 mysql_stmt_reset()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571533776"></a><p>
        <code class="literal">my_bool mysql_stmt_reset(MYSQL_STMT *stmt)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-reset-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Resets a prepared statement on client and server to state
          after prepare. It resets the statement on the server, data
          sent using
          <a class="link" href="connectors-apis.html#mysql-stmt-send-long-data" title="27.8.11.26 mysql_stmt_send_long_data()"><code class="literal">mysql_stmt_send_long_data()</code></a>,
          unbuffered result sets and current errors. It does not clear
          bindings or stored result sets. Stored result sets will be
          cleared when executing the prepared statement (or closing it).
        </p><p>
          To re-prepare the statement with another query, use
          <a class="link" href="connectors-apis.html#mysql-stmt-prepare" title="27.8.11.21 mysql_stmt_prepare()"><code class="literal">mysql_stmt_prepare()</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-reset-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-reset-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-result-metadata"></a>27.8.11.23 mysql_stmt_result_metadata()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571512112"></a><p>
        <code class="literal">MYSQL_RES *mysql_stmt_result_metadata(MYSQL_STMT
        *stmt)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-result-metadata-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          If a statement passed to
          <a class="link" href="connectors-apis.html#mysql-stmt-prepare" title="27.8.11.21 mysql_stmt_prepare()"><code class="literal">mysql_stmt_prepare()</code></a> is one
          that produces a result set,
          <a class="link" href="connectors-apis.html#mysql-stmt-result-metadata" title="27.8.11.23 mysql_stmt_result_metadata()"><code class="literal">mysql_stmt_result_metadata()</code></a>
          returns the result set metadata in the form of a pointer to a
          <code class="literal">MYSQL_RES</code> structure that can be used to
          process the meta information such as number of fields and
          individual field information. This result set pointer can be
          passed as an argument to any of the field-based API functions
          that process result set metadata, such as:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="connectors-apis.html#mysql-num-fields" title="27.8.7.48 mysql_num_fields()"><code class="literal">mysql_num_fields()</code></a>
            </p></li><li class="listitem"><p>
              <a class="link" href="connectors-apis.html#mysql-fetch-field" title="27.8.7.17 mysql_fetch_field()"><code class="literal">mysql_fetch_field()</code></a>
            </p></li><li class="listitem"><p>
              <a class="link" href="connectors-apis.html#mysql-fetch-field-direct" title="27.8.7.18 mysql_fetch_field_direct()"><code class="literal">mysql_fetch_field_direct()</code></a>
            </p></li><li class="listitem"><p>
              <a class="link" href="connectors-apis.html#mysql-fetch-fields" title="27.8.7.19 mysql_fetch_fields()"><code class="literal">mysql_fetch_fields()</code></a>
            </p></li><li class="listitem"><p>
              <a class="link" href="connectors-apis.html#mysql-field-count" title="27.8.7.22 mysql_field_count()"><code class="literal">mysql_field_count()</code></a>
            </p></li><li class="listitem"><p>
              <a class="link" href="connectors-apis.html#mysql-field-seek" title="27.8.7.23 mysql_field_seek()"><code class="literal">mysql_field_seek()</code></a>
            </p></li><li class="listitem"><p>
              <a class="link" href="connectors-apis.html#mysql-field-tell" title="27.8.7.24 mysql_field_tell()"><code class="literal">mysql_field_tell()</code></a>
            </p></li><li class="listitem"><p>
              <a class="link" href="connectors-apis.html#mysql-free-result" title="27.8.7.25 mysql_free_result()"><code class="literal">mysql_free_result()</code></a>
</p></li></ul>
</div>
<p>
          The result set structure should be freed when you are done
          with it, which you can do by passing it to
          <a class="link" href="connectors-apis.html#mysql-free-result" title="27.8.7.25 mysql_free_result()"><code class="literal">mysql_free_result()</code></a>. This is
          similar to the way you free a result set obtained from a call
          to <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a>.
        </p><p>
          The result set returned by
          <a class="link" href="connectors-apis.html#mysql-stmt-result-metadata" title="27.8.11.23 mysql_stmt_result_metadata()"><code class="literal">mysql_stmt_result_metadata()</code></a>
          contains only metadata. It does not contain any row results.
          The rows are obtained by using the statement handler with
          <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-result-metadata-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          A <code class="literal">MYSQL_RES</code> result structure.
          <code class="literal">NULL</code> if no meta information exists for the
          prepared query.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-result-metadata-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_out_of_memory"><code class="literal">CR_OUT_OF_MEMORY</code></a>
            </p><p>
              Out of memory.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-result-metadata-example"></a>Example</h5>

</div>

</div>

</div>
<p>
          See the Example in <a class="xref" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()">Section 27.8.11.11, “mysql_stmt_fetch()”</a>.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-row-seek"></a>27.8.11.24 mysql_stmt_row_seek()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571468976"></a><p>
        <code class="literal">MYSQL_ROW_OFFSET mysql_stmt_row_seek(MYSQL_STMT *stmt,
        MYSQL_ROW_OFFSET offset)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-row-seek-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Sets the row cursor to an arbitrary row in a statement result
          set. The <code class="literal">offset</code> value is a row offset that
          should be a value returned from
          <a class="link" href="connectors-apis.html#mysql-stmt-row-tell" title="27.8.11.25 mysql_stmt_row_tell()"><code class="literal">mysql_stmt_row_tell()</code></a> or from
          <a class="link" href="connectors-apis.html#mysql-stmt-row-seek" title="27.8.11.24 mysql_stmt_row_seek()"><code class="literal">mysql_stmt_row_seek()</code></a>. This
          value is not a row number; if you want to seek to a row within
          a result set by number, use
          <a class="link" href="connectors-apis.html#mysql-stmt-data-seek" title="27.8.11.7 mysql_stmt_data_seek()"><code class="literal">mysql_stmt_data_seek()</code></a>
          instead.
        </p><p>
          This function requires that the result set structure contains
          the entire result of the query, so
          <a class="link" href="connectors-apis.html#mysql-stmt-row-seek" title="27.8.11.24 mysql_stmt_row_seek()"><code class="literal">mysql_stmt_row_seek()</code></a> may be
          used only in conjunction with
          <a class="link" href="connectors-apis.html#mysql-stmt-store-result" title="27.8.11.28 mysql_stmt_store_result()"><code class="literal">mysql_stmt_store_result()</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-row-seek-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          The previous value of the row cursor. This value may be passed
          to a subsequent call to
          <a class="link" href="connectors-apis.html#mysql-stmt-row-seek" title="27.8.11.24 mysql_stmt_row_seek()"><code class="literal">mysql_stmt_row_seek()</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-row-seek-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-row-tell"></a>27.8.11.25 mysql_stmt_row_tell()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571451520"></a><p>
        <code class="literal">MYSQL_ROW_OFFSET mysql_stmt_row_tell(MYSQL_STMT
        *stmt)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-row-tell-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns the current position of the row cursor for the last
          <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a>. This value
          can be used as an argument to
          <a class="link" href="connectors-apis.html#mysql-stmt-row-seek" title="27.8.11.24 mysql_stmt_row_seek()"><code class="literal">mysql_stmt_row_seek()</code></a>.
        </p><p>
          You should use
          <a class="link" href="connectors-apis.html#mysql-stmt-row-tell" title="27.8.11.25 mysql_stmt_row_tell()"><code class="literal">mysql_stmt_row_tell()</code></a> only
          after
          <a class="link" href="connectors-apis.html#mysql-stmt-store-result" title="27.8.11.28 mysql_stmt_store_result()"><code class="literal">mysql_stmt_store_result()</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-row-tell-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          The current offset of the row cursor.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-row-tell-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-send-long-data"></a>27.8.11.26 mysql_stmt_send_long_data()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571437552"></a><p>
        <code class="literal">my_bool mysql_stmt_send_long_data(MYSQL_STMT *stmt,
        unsigned int parameter_number, const char *data, unsigned long
        length)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-send-long-data-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Enables an application to send parameter data to the server in
          pieces (or <span class="quote">“<span class="quote">chunks</span>”</span>). Call this function after
          <a class="link" href="connectors-apis.html#mysql-stmt-bind-param" title="27.8.11.4 mysql_stmt_bind_param()"><code class="literal">mysql_stmt_bind_param()</code></a> and
          before <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a>.
          It can be called multiple times to send the parts of a
          character or binary data value for a column, which must be one
          of the <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">TEXT</code></a> or
          <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">BLOB</code></a> data types.
        </p><p>
          <code class="literal">parameter_number</code> indicates which parameter
          to associate the data with. Parameters are numbered beginning
          with 0. <code class="literal">data</code> is a pointer to a buffer
          containing data to be sent, and <code class="literal">length</code>
          indicates the number of bytes in the buffer.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
            The next
            <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a> call
            ignores the bind buffer for all parameters that have been
            used with
            <a class="link" href="connectors-apis.html#mysql-stmt-send-long-data" title="27.8.11.26 mysql_stmt_send_long_data()"><code class="literal">mysql_stmt_send_long_data()</code></a>
            since last
            <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a> or
            <a class="link" href="connectors-apis.html#mysql-stmt-reset" title="27.8.11.22 mysql_stmt_reset()"><code class="literal">mysql_stmt_reset()</code></a>.
</p>
</div>
<p>
          If you want to reset/forget the sent data, you can do it with
          <a class="link" href="connectors-apis.html#mysql-stmt-reset" title="27.8.11.22 mysql_stmt_reset()"><code class="literal">mysql_stmt_reset()</code></a>. See
          <a class="xref" href="connectors-apis.html#mysql-stmt-reset" title="27.8.11.22 mysql_stmt_reset()">Section 27.8.11.22, “mysql_stmt_reset()”</a>.
        </p><p>
          The <a class="link" href="server-administration.html#sysvar_max_allowed_packet"><code class="literal">max_allowed_packet</code></a> system
          variable controls the maximum size of parameter values that
          can be sent with
          <a class="link" href="connectors-apis.html#mysql-stmt-send-long-data" title="27.8.11.26 mysql_stmt_send_long_data()"><code class="literal">mysql_stmt_send_long_data()</code></a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-send-long-data-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-send-long-data-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_invalid_buffer_use"><code class="literal">CR_INVALID_BUFFER_USE</code></a>
            </p><p>
              The parameter does not have a string or binary type.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_invalid_parameter_no"><code class="literal">CR_INVALID_PARAMETER_NO</code></a>
            </p><p>
              Invalid parameter number.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_out_of_memory"><code class="literal">CR_OUT_OF_MEMORY</code></a>
            </p><p>
              Out of memory.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-send-long-data-example"></a>Example</h5>

</div>

</div>

</div>
<p>
          The following example demonstrates how to send the data for a
          <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">TEXT</code></a> column in chunks. It
          inserts the data value <code class="literal">'MySQL - The most popular Open
          Source database'</code> into the
          <code class="literal">text_column</code> column. The
          <code class="literal">mysql</code> variable is assumed to be a valid
          connection handler.
        </p><pre data-lang="c" class="programlisting">
#define INSERT_QUERY "INSERT INTO \
                      test_long_data(text_column) VALUES(?)"

MYSQL_BIND bind[1];
long       length;

stmt = mysql_stmt_init(mysql);
if (!stmt)
{
  fprintf(stderr, " mysql_stmt_init(), out of memory\n");
  exit(0);
}
if (mysql_stmt_prepare(stmt, INSERT_QUERY, strlen(INSERT_QUERY)))
{
  fprintf(stderr, "\n mysql_stmt_prepare(), INSERT failed");
  fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
  exit(0);
}
 memset(bind, 0, sizeof(bind));
 bind[0].buffer_type= MYSQL_TYPE_STRING;
 bind[0].length= &amp;length;
 bind[0].is_null= 0;

/* Bind the buffers */
if (mysql_stmt_bind_param(stmt, bind))
{
  fprintf(stderr, "\n param bind failed");
  fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
  exit(0);
}

 /* Supply data in chunks to server */
 if (mysql_stmt_send_long_data(stmt,0,"MySQL",5))
{
  fprintf(stderr, "\n send_long_data failed");
  fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
  exit(0);
}

 /* Supply the next piece of data */
 if (mysql_stmt_send_long_data(stmt,0,
           " - The most popular Open Source database",40))
{
  fprintf(stderr, "\n send_long_data failed");
  fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
  exit(0);
}

 /* Now, execute the query */
 if (mysql_stmt_execute(stmt))
{
  fprintf(stderr, "\n mysql_stmt_execute failed");
  fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
  exit(0);
}
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-sqlstate"></a>27.8.11.27 mysql_stmt_sqlstate()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571384320"></a><p>
        <code class="literal">const char *mysql_stmt_sqlstate(MYSQL_STMT
        *stmt)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-sqlstate-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          For the statement specified by <code class="literal">stmt</code>,
          <a class="link" href="connectors-apis.html#mysql-stmt-sqlstate" title="27.8.11.27 mysql_stmt_sqlstate()"><code class="literal">mysql_stmt_sqlstate()</code></a> returns
          a null-terminated string containing the SQLSTATE error code
          for the most recently invoked prepared statement API function
          that can succeed or fail. The error code consists of five
          characters. <code class="literal">"00000"</code> means <span class="quote">“<span class="quote">no
          error.</span>”</span> The values are specified by ANSI SQL and ODBC.
          For a list of possible values, see
          <a class="xref" href="error-handling.html" title="Appendix B Errors, Error Codes, and Common Problems">Appendix B, <i>Errors, Error Codes, and Common Problems</i></a>.
        </p><p>
          Not all MySQL errors are mapped to SQLSTATE codes. The value
          <code class="literal">"HY000"</code> (general error) is used for
          unmapped errors.
        </p><p>
          If the failed statement API function was
          <a class="link" href="connectors-apis.html#mysql-stmt-close" title="27.8.11.6 mysql_stmt_close()"><code class="literal">mysql_stmt_close()</code></a>, do not
          call <a class="link" href="connectors-apis.html#mysql-stmt-sqlstate" title="27.8.11.27 mysql_stmt_sqlstate()"><code class="literal">mysql_stmt_sqlstate()</code></a> to
          obtain error information because
          <a class="link" href="connectors-apis.html#mysql-stmt-close" title="27.8.11.6 mysql_stmt_close()"><code class="literal">mysql_stmt_close()</code></a> makes the
          statement handler invalid. Call
          <a class="link" href="connectors-apis.html#mysql-sqlstate" title="27.8.7.72 mysql_sqlstate()"><code class="literal">mysql_sqlstate()</code></a> instead.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-sqlstate-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          A null-terminated character string containing the SQLSTATE
          error code.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-stmt-store-result"></a>27.8.11.28 mysql_stmt_store_result()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571366624"></a><p>
        <code class="literal">int mysql_stmt_store_result(MYSQL_STMT *stmt)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-stmt-store-result-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Result sets are produced by calling
          <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a> to
          executed prepared statements for SQL statements such as
          <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a>,
          <a class="link" href="sql-syntax.html#show" title="13.7.5 SHOW Syntax"><code class="literal">SHOW</code></a>,
          <a class="link" href="sql-syntax.html#describe" title="13.8.1 DESCRIBE Syntax"><code class="literal">DESCRIBE</code></a>, and
          <a class="link" href="sql-syntax.html#explain" title="13.8.2 EXPLAIN Syntax"><code class="literal">EXPLAIN</code></a>. By default, result
          sets for successfully executed prepared statements are not
          buffered on the client and
          <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a> fetches
          them one at a time from the server. To cause the complete
          result set to be buffered on the client, call
          <a class="link" href="connectors-apis.html#mysql-stmt-store-result" title="27.8.11.28 mysql_stmt_store_result()"><code class="literal">mysql_stmt_store_result()</code></a>
          after binding data buffers with
          <a class="link" href="connectors-apis.html#mysql-stmt-bind-result" title="27.8.11.5 mysql_stmt_bind_result()"><code class="literal">mysql_stmt_bind_result()</code></a> and
          before calling
          <a class="link" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()"><code class="literal">mysql_stmt_fetch()</code></a> to fetch
          rows. (For an example, see
          <a class="xref" href="connectors-apis.html#mysql-stmt-fetch" title="27.8.11.11 mysql_stmt_fetch()">Section 27.8.11.11, “mysql_stmt_fetch()”</a>.)
        </p><p>
          <a class="link" href="connectors-apis.html#mysql-stmt-store-result" title="27.8.11.28 mysql_stmt_store_result()"><code class="literal">mysql_stmt_store_result()</code></a> is
          optional for result set processing, unless you will call
          <a class="link" href="connectors-apis.html#mysql-stmt-data-seek" title="27.8.11.7 mysql_stmt_data_seek()"><code class="literal">mysql_stmt_data_seek()</code></a>,
          <a class="link" href="connectors-apis.html#mysql-stmt-row-seek" title="27.8.11.24 mysql_stmt_row_seek()"><code class="literal">mysql_stmt_row_seek()</code></a>, or
          <a class="link" href="connectors-apis.html#mysql-stmt-row-tell" title="27.8.11.25 mysql_stmt_row_tell()"><code class="literal">mysql_stmt_row_tell()</code></a>. Those
          functions require a seekable result set.
        </p><p>
          It is unnecessary to call
          <a class="link" href="connectors-apis.html#mysql-stmt-store-result" title="27.8.11.28 mysql_stmt_store_result()"><code class="literal">mysql_stmt_store_result()</code></a>
          after executing an SQL statement that does not produce a
          result set, but if you do, it does not harm or cause any
          notable performance problem. You can detect whether the
          statement produced a result set by checking if
          <a class="link" href="connectors-apis.html#mysql-stmt-result-metadata" title="27.8.11.23 mysql_stmt_result_metadata()"><code class="literal">mysql_stmt_result_metadata()</code></a>
          returns <code class="literal">NULL</code>. For more information, refer
          to <a class="xref" href="connectors-apis.html#mysql-stmt-result-metadata" title="27.8.11.23 mysql_stmt_result_metadata()">Section 27.8.11.23, “mysql_stmt_result_metadata()”</a>.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
            MySQL does not by default calculate
            <code class="literal">MYSQL_FIELD-&gt;max_length</code> for all
            columns in
            <a class="link" href="connectors-apis.html#mysql-stmt-store-result" title="27.8.11.28 mysql_stmt_store_result()"><code class="literal">mysql_stmt_store_result()</code></a>
            because calculating this would slow down
            <a class="link" href="connectors-apis.html#mysql-stmt-store-result" title="27.8.11.28 mysql_stmt_store_result()"><code class="literal">mysql_stmt_store_result()</code></a>
            considerably and most applications do not need
            <code class="literal">max_length</code>. If you want
            <code class="literal">max_length</code> to be updated, you can call
            <a class="link" href="connectors-apis.html#mysql-stmt-attr-set" title="27.8.11.3 mysql_stmt_attr_set()"><code class="literal">mysql_stmt_attr_set(MYSQL_STMT,
            STMT_ATTR_UPDATE_MAX_LENGTH, &amp;flag)</code></a> to enable
            this. See <a class="xref" href="connectors-apis.html#mysql-stmt-attr-set" title="27.8.11.3 mysql_stmt_attr_set()">Section 27.8.11.3, “mysql_stmt_attr_set()”</a>.
</p>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-store-result-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-stmt-store-result-errors"></a>Errors</h5>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_commands_out_of_sync"><code class="literal">CR_COMMANDS_OUT_OF_SYNC</code></a>
            </p><p>
              Commands were executed in an improper order.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_out_of_memory"><code class="literal">CR_OUT_OF_MEMORY</code></a>
            </p><p>
              Out of memory.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_gone_error"><code class="literal">CR_SERVER_GONE_ERROR</code></a>
            </p><p>
              The MySQL server has gone away.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_server_lost"><code class="literal">CR_SERVER_LOST</code></a>
            </p><p>
              The connection to the server was lost during the query.
            </p></li><li class="listitem"><p>
              <a class="link" href="error-handling.html#error_cr_unknown_error"><code class="literal">CR_UNKNOWN_ERROR</code></a>
            </p><p>
              An unknown error occurred.
</p></li></ul>
</div>

</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="c-api-thread-functions"></a>27.8.12 C API Threaded Function Descriptions</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="connectors-apis.html#my-init">27.8.12.1 my_init()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-thread-end">27.8.12.2 mysql_thread_end()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-thread-init">27.8.12.3 mysql_thread_init()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-thread-safe">27.8.12.4 mysql_thread_safe()</a></span></dt></dl>
</div>
<p>
      To create a threaded client, use the functions described in the
      following sections. See also
      <a class="xref" href="connectors-apis.html#c-api-threaded-clients" title="27.8.4.3 Writing C API Threaded Client Programs">Section 27.8.4.3, “Writing C API Threaded Client Programs”</a>.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="my-init"></a>27.8.12.1 my_init()</h4>
</div>
</div>
</div>
<a class="indexterm" name="idm140710571313424"></a><p>
        <code class="literal">void my_init(void)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="my-init-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          <a class="link" href="connectors-apis.html#my-init" title="27.8.12.1 my_init()"><code class="literal">my_init()</code></a> initializes some
          global variables that MySQL needs. It also calls
          <a class="link" href="connectors-apis.html#mysql-thread-init" title="27.8.12.3 mysql_thread_init()"><code class="literal">mysql_thread_init()</code></a> for this
          thread.
        </p><p>
          It is necessary for <a class="link" href="connectors-apis.html#my-init" title="27.8.12.1 my_init()"><code class="literal">my_init()</code></a>
          to be called early in the initialization phase of a program's
          use of the MySQL client library. However,
          <a class="link" href="connectors-apis.html#my-init" title="27.8.12.1 my_init()"><code class="literal">my_init()</code></a> is automatically
          called by <a class="link" href="connectors-apis.html#mysql-init" title="27.8.7.37 mysql_init()"><code class="literal">mysql_init()</code></a>,
          <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a>,
          <a class="link" href="connectors-apis.html#mysql-server-init" title="27.8.13.2 mysql_server_init()"><code class="literal">mysql_server_init()</code></a>, and
          <a class="link" href="connectors-apis.html#mysql-connect" title="27.8.7.7 mysql_connect()"><code class="literal">mysql_connect()</code></a>. If you ensure
          that your program invokes one of those functions before any
          other MySQL calls, there is no need to invoke
          <a class="link" href="connectors-apis.html#my-init" title="27.8.12.1 my_init()"><code class="literal">my_init()</code></a> explicitly.
        </p><p>
          To access the prototype for
          <a class="link" href="connectors-apis.html#my-init" title="27.8.12.1 my_init()"><code class="literal">my_init()</code></a>, your program should
          include these header files:
        </p><pre data-lang="c" class="programlisting">
#include &lt;my_global.h&gt;
#include &lt;my_sys.h&gt;
</pre>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="my-init-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-thread-end"></a>27.8.12.2 mysql_thread_end()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571292336"></a><p>
        <code class="literal">void mysql_thread_end(void)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-thread-end-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Call this function before calling
          <code class="literal">pthread_exit()</code> to free memory allocated by
          <a class="link" href="connectors-apis.html#mysql-thread-init" title="27.8.12.3 mysql_thread_init()"><code class="literal">mysql_thread_init()</code></a>.
        </p><p>
          <a class="link" href="connectors-apis.html#mysql-thread-end" title="27.8.12.2 mysql_thread_end()"><code class="literal">mysql_thread_end()</code></a>
          <span class="emphasis"><em>is not invoked automatically by the client
          library</em></span>.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              For release/production builds without debugging support
              enabled,
              <a class="link" href="connectors-apis.html#mysql-thread-end" title="27.8.12.2 mysql_thread_end()"><code class="literal">mysql_thread_end()</code></a> need
              not be called.
            </p></li><li class="listitem"><p>
              For debug builds,
              <a class="link" href="connectors-apis.html#mysql-thread-init" title="27.8.12.3 mysql_thread_init()"><code class="literal">mysql_thread_init()</code></a>
              allocates debugging information for the DBUG package (see
              <a class="xref" href="extending-mysql.html#dbug-package" title="28.5.3 The DBUG Package">Section 28.5.3, “The DBUG Package”</a>).
              <a class="link" href="connectors-apis.html#mysql-thread-end" title="27.8.12.2 mysql_thread_end()"><code class="literal">mysql_thread_end()</code></a> must be
              called for each
              <a class="link" href="connectors-apis.html#mysql-thread-init" title="27.8.12.3 mysql_thread_init()"><code class="literal">mysql_thread_init()</code></a> call
              to avoid a memory leak.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-thread-end-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-thread-init"></a>27.8.12.3 mysql_thread_init()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571273632"></a><p>
        <code class="literal">my_bool mysql_thread_init(void)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-thread-init-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          This function must be called early within each created thread
          to initialize thread-specific variables. However, you may not
          necessarily need to invoke it explicitly:
          <a class="link" href="connectors-apis.html#mysql-thread-init" title="27.8.12.3 mysql_thread_init()"><code class="literal">mysql_thread_init()</code></a> is
          automatically called by
          <a class="link" href="connectors-apis.html#my-init" title="27.8.12.1 my_init()"><code class="literal">my_init()</code></a>, which itself is
          automatically called by
          <a class="link" href="connectors-apis.html#mysql-init" title="27.8.7.37 mysql_init()"><code class="literal">mysql_init()</code></a>,
          <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a>,
          <a class="link" href="connectors-apis.html#mysql-server-init" title="27.8.13.2 mysql_server_init()"><code class="literal">mysql_server_init()</code></a>, and
          <a class="link" href="connectors-apis.html#mysql-connect" title="27.8.7.7 mysql_connect()"><code class="literal">mysql_connect()</code></a>. If you invoke
          any of those functions,
          <a class="link" href="connectors-apis.html#mysql-thread-init" title="27.8.12.3 mysql_thread_init()"><code class="literal">mysql_thread_init()</code></a> is called
          for you.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-thread-init-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-thread-safe"></a>27.8.12.4 mysql_thread_safe()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571257792"></a><p>
        <code class="literal">unsigned int mysql_thread_safe(void)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-thread-safe-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          This function indicates whether the client library is compiled
          as thread-safe.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-thread-safe-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          1 if the client library is thread-safe, 0 otherwise.
</p>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="c-api-embedded-server-functions"></a>27.8.13 C API Embedded Server Function Descriptions</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="connectors-apis.html#mysql-server-end">27.8.13.1 mysql_server_end()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-server-init">27.8.13.2 mysql_server_init()</a></span></dt></dl>
</div>
<p>
      MySQL applications can be written to use an embedded server. See
      <a class="xref" href="connectors-apis.html#libmysqld" title="27.7 libmysqld, the Embedded MySQL Server Library">Section 27.7, “libmysqld, the Embedded MySQL Server Library”</a>. To write such an application, you
      must link it against the <code class="literal">libmysqld</code> library by
      using the <code class="option">-lmysqld</code> flag rather than linking it
      against the <code class="literal">libmysqlclient</code> client library by
      using the <code class="option">-lmysqlclient</code> flag. However, the calls
      to initialize and finalize the library are the same whether you
      write a client application or one that uses the embedded server:
      Call <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a> to
      initialize the library and
      <a class="link" href="connectors-apis.html#mysql-library-end" title="27.8.7.40 mysql_library_end()"><code class="literal">mysql_library_end()</code></a> when you are
      done with it. See <a class="xref" href="connectors-apis.html#c-api-function-overview" title="27.8.6 C API Function Overview">Section 27.8.6, “C API Function Overview”</a>.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-server-end"></a>27.8.13.1 mysql_server_end()</h4>
</div>
</div>
</div>
<a class="indexterm" name="idm140710571242736"></a><p>
        <code class="literal">void mysql_server_end(void)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-server-end-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          This function finalizes the MySQL library, which should be
          done when you are done using the library. However,
          <a class="link" href="connectors-apis.html#mysql-server-end" title="27.8.13.1 mysql_server_end()"><code class="literal">mysql_server_end()</code></a> is
          deprecated and
          <a class="link" href="connectors-apis.html#mysql-library-end" title="27.8.7.40 mysql_library_end()"><code class="literal">mysql_library_end()</code></a> should be
          used instead. See <a class="xref" href="connectors-apis.html#mysql-library-end" title="27.8.7.40 mysql_library_end()">Section 27.8.7.40, “mysql_library_end()”</a>.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
            To avoid memory leaks after the application is done using
            the library (for example, after closing the connection to
            the server), be sure to call
            <a class="link" href="connectors-apis.html#mysql-server-end" title="27.8.13.1 mysql_server_end()"><code class="literal">mysql_server_end()</code></a> (or
            <a class="link" href="connectors-apis.html#mysql-library-end" title="27.8.7.40 mysql_library_end()"><code class="literal">mysql_library_end()</code></a>)
            explicitly. This enables memory managment to be performed to
            clean up and free resources used by the library.
</p>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-server-end-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          None.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-server-init"></a>27.8.13.2 mysql_server_init()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571229136"></a><p>
        <code class="literal">int mysql_server_init(int argc, char **argv, char
        **groups)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-server-init-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          This function initializes the MySQL client library, which must
          be done before you call any other MySQL function. However,
          <a class="link" href="connectors-apis.html#mysql-server-init" title="27.8.13.2 mysql_server_init()"><code class="literal">mysql_server_init()</code></a> is
          deprecated and you should call
          <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a> instead.
          See <a class="xref" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()">Section 27.8.7.41, “mysql_library_init()”</a>.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
            To avoid memory leaks after the application is done using
            the library (for example, after closing the connection to
            the server), be sure to call
            <a class="link" href="connectors-apis.html#mysql-server-end" title="27.8.13.1 mysql_server_end()"><code class="literal">mysql_server_end()</code></a> (or
            <a class="link" href="connectors-apis.html#mysql-library-end" title="27.8.7.40 mysql_library_end()"><code class="literal">mysql_library_end()</code></a>)
            explicitly. This enables memory managment to be performed to
            clean up and free resources used by the library. See
            <a class="xref" href="connectors-apis.html#mysql-library-end" title="27.8.7.40 mysql_library_end()">Section 27.8.7.40, “mysql_library_end()”</a>.
</p>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-server-init-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success. Nonzero if an error occurred.
</p>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="c-api-plugin-functions"></a>27.8.14 C API Client Plugin Functions</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="connectors-apis.html#mysql-client-find-plugin">27.8.14.1 mysql_client_find_plugin()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-client-register-plugin">27.8.14.2 mysql_client_register_plugin()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-load-plugin">27.8.14.3 mysql_load_plugin()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-load-plugin-v">27.8.14.4 mysql_load_plugin_v()</a></span></dt><dt><span class="section"><a href="connectors-apis.html#mysql-plugin-options">27.8.14.5 mysql_plugin_options()</a></span></dt></dl>
</div>
<p>
      This section describes functions used for the client-side plugin
      API. They enable management of client plugins. For a description
      of the <code class="literal">st_mysql_client_plugin</code> structure used by
      these functions, see <a class="xref" href="extending-mysql.html#client-plugin-descriptors" title="28.2.4.2.3 Client Plugin Descriptors">Section 28.2.4.2.3, “Client Plugin Descriptors”</a>.
    </p><p>
      It is unlikely that a client program needs to call the functions
      in this section. For example, a client that supports the use of
      authentication plugins normally causes a plugin to be loaded by
      calling <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> to set the
      <code class="literal">MYSQL_DEFAULT_AUTH</code> and
      <code class="literal">MYSQL_PLUGIN_DIR</code> options:
    </p><pre data-lang="c" class="programlisting">
char *plugin_dir = "<em class="replaceable"><code>path_to_plugin_dir</code></em>";
char *default_auth = "<em class="replaceable"><code>plugin_name</code></em>";

/* ... process command-line options ... */

mysql_options(&amp;mysql, MYSQL_PLUGIN_DIR, plugin_dir);
mysql_options(&amp;mysql, MYSQL_DEFAULT_AUTH, default_auth);
</pre><p>
      Typically, the program will also accept
      <code class="option">--plugin-dir</code> and <code class="option">--default-auth</code>
      options that enable users to override the default values.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-client-find-plugin"></a>27.8.14.1 mysql_client_find_plugin()</h4>
</div>
</div>
</div>
<a class="indexterm" name="idm140710571204432"></a><p>
        <code class="literal">struct st_mysql_client_plugin
        *mysql_client_find_plugin(MYSQL *mysql, const char *name, int
        type)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-client-find-plugin-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Returns a pointer to a loaded plugin, loading the plugin first
          if necessary. An error occurs if the type is invalid or the
          plugin cannot be found or loaded.
        </p><p>
          Specify the parameters as follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <code class="literal">mysql</code>: A pointer to a
              <code class="literal">MYSQL</code> structure. The plugin API does
              not require a connection to a MySQL server, but this
              structure must be properly initialized. The structure is
              used to obtain connection-related information.
            </p></li><li class="listitem"><p>
              <code class="literal">name</code>: The plugin name.
            </p></li><li class="listitem"><p>
              <code class="literal">type</code>: The plugin type.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-client-find-plugin-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          A pointer to the plugin for success. <code class="literal">NULL</code>
          if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-client-find-plugin-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          To check for errors, call the
          <a class="link" href="connectors-apis.html#mysql-error" title="27.8.7.15 mysql_error()"><code class="literal">mysql_error()</code></a> or
          <a class="link" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()"><code class="literal">mysql_errno()</code></a> function. See
          <a class="xref" href="connectors-apis.html#mysql-error" title="27.8.7.15 mysql_error()">Section 27.8.7.15, “mysql_error()”</a>, and
          <a class="xref" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()">Section 27.8.7.14, “mysql_errno()”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-client-find-plugin-example"></a>Example</h5>

</div>

</div>

</div>
<pre data-lang="c" class="programlisting">
MYSQL mysql;
struct st_mysql_client_plugin *p;

if ((p = mysql_client_find_plugin(&amp;mysql, "myplugin",
                                  MYSQL_CLIENT_AUTHENTICATION_PLUGIN, 0)))
{
  printf("Plugin version: %d.%d.%d\n", p-&gt;version[0], p-&gt;version[1], p-&gt;version[2]);
}
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-client-register-plugin"></a>27.8.14.2 mysql_client_register_plugin()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571181888"></a><p>
        <code class="literal">struct st_mysql_client_plugin
        *mysql_client_register_plugin(MYSQL *mysql, struct
        st_mysql_client_plugin *plugin)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-client-register-plugin-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Adds a plugin structure to the list of loaded plugins. An
          error occurs if the plugin is already loaded.
        </p><p>
          Specify the parameters as follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <code class="literal">mysql</code>: A pointer to a
              <code class="literal">MYSQL</code> structure. The plugin API does
              not require a connection to a MySQL server, but this
              structure must be properly initialized. The structure is
              used to obtain connection-related information.
            </p></li><li class="listitem"><p>
              <code class="literal">plugin</code>: A pointer to the plugin
              structure.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-client-register-plugin-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          A pointer to the plugin for success. <code class="literal">NULL</code>
          if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-client-register-plugin-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          To check for errors, call the
          <a class="link" href="connectors-apis.html#mysql-error" title="27.8.7.15 mysql_error()"><code class="literal">mysql_error()</code></a> or
          <a class="link" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()"><code class="literal">mysql_errno()</code></a> function. See
          <a class="xref" href="connectors-apis.html#mysql-error" title="27.8.7.15 mysql_error()">Section 27.8.7.15, “mysql_error()”</a>, and
          <a class="xref" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()">Section 27.8.7.14, “mysql_errno()”</a>.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-load-plugin"></a>27.8.14.3 mysql_load_plugin()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571163760"></a><p>
        <code class="literal">struct st_mysql_client_plugin *mysql_load_plugin(MYSQL
        *mysql, const char *name, int type, int argc, ...)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-load-plugin-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Loads a MySQL client plugin, specified by name and type. An
          error occurs if the type is invalid or the plugin cannot be
          loaded.
        </p><p>
          It is not possible to load multiple plugins of the same type.
          An error occurs if you try to load a plugin of a type already
          loaded.
        </p><p>
          Specify the parameters as follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <code class="literal">mysql</code>: A pointer to a
              <code class="literal">MYSQL</code> structure. The plugin API does
              not require a connection to a MySQL server, but this
              structure must be properly initialized. The structure is
              used to obtain connection-related information.
            </p></li><li class="listitem"><p>
              <code class="literal">name</code>: The name of the plugin to load.
            </p></li><li class="listitem"><p>
              <code class="literal">type</code>: The type of plugin to load, or
              −1 to disable type checking. If type is not
              −1, only plugins matching the type are considered
              for loading.
            </p></li><li class="listitem"><p>
              <code class="literal">argc</code>: The number of following arguments
              (0 if there are none). Interpretation of any following
              arguments depends on the plugin type.
</p></li></ul>
</div>
<a class="indexterm" name="idm140710571150880"></a><a class="indexterm" name="idm140710571149792"></a><p>
          Another way to cause plugins to be loaded is to set the
          <code class="literal">LIBMYSQL_PLUGINS</code> environment variable to a
          semicolon-separated list of plugin names. For example:
        </p><pre data-lang="terminal" class="programlisting">
shell&gt; export LIBMYSQL_PLUGINS="myplugin1;myplugin2"
</pre><p>
          Plugins named by <code class="literal">LIBMYSQL_PLUGINS</code> are
          loaded when the client program calls
          <a class="link" href="connectors-apis.html#mysql-library-init" title="27.8.7.41 mysql_library_init()"><code class="literal">mysql_library_init()</code></a>. No error
          is reported if problems occur loading these plugins.
        </p><a class="indexterm" name="idm140710571143456"></a><a class="indexterm" name="idm140710571142352"></a><p>
          The <code class="literal">LIBMYSQL_PLUGIN_DIR</code> environment
          variable can be set to the path name of the directory in which
          to look for client plugins. This variable is used in two ways:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              During client plugin preloading, the value of the
              <code class="option">--plugin-dir</code> option is not available, so
              client plugin loading fails unless the plugins are located
              in the hardwired default directory. If the plugins are
              located elsewhere, <code class="literal">LIBMYSQL_PLUGIN_DIR</code>
              environment variable can be set to the proper directory to
              enable plugin preloading to succeed.
            </p></li><li class="listitem"><p>
              For explicit client plugin loading, the
              <a class="link" href="connectors-apis.html#mysql-load-plugin" title="27.8.14.3 mysql_load_plugin()"><code class="literal">mysql_load_plugin()</code></a> and
              <a class="link" href="connectors-apis.html#mysql-load-plugin-v" title="27.8.14.4 mysql_load_plugin_v()"><code class="literal">mysql_load_plugin_v()</code></a> C
              API functions use the
              <code class="literal">LIBMYSQL_PLUGIN_DIR</code> value if it exists
              and the <code class="option">--plugin-dir</code> option was not
              given. If <code class="option">--plugin-dir</code> is given,
              <a class="link" href="connectors-apis.html#mysql-load-plugin" title="27.8.14.3 mysql_load_plugin()"><code class="literal">mysql_load_plugin()</code></a> and
              <a class="link" href="connectors-apis.html#mysql-load-plugin-v" title="27.8.14.4 mysql_load_plugin_v()"><code class="literal">mysql_load_plugin_v()</code></a>
              ignore <code class="literal">LIBMYSQL_PLUGIN_DIR</code>.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-load-plugin-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          A pointer to the plugin if it was loaded successfully.
          <code class="literal">NULL</code> if an error occurred.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-load-plugin-errors"></a>Errors</h5>

</div>

</div>

</div>
<p>
          To check for errors, call the
          <a class="link" href="connectors-apis.html#mysql-error" title="27.8.7.15 mysql_error()"><code class="literal">mysql_error()</code></a> or
          <a class="link" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()"><code class="literal">mysql_errno()</code></a> function. See
          <a class="xref" href="connectors-apis.html#mysql-error" title="27.8.7.15 mysql_error()">Section 27.8.7.15, “mysql_error()”</a>, and
          <a class="xref" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()">Section 27.8.7.14, “mysql_errno()”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-load-plugin-example"></a>Example</h5>

</div>

</div>

</div>
<pre data-lang="c" class="programlisting">
MYSQL mysql;

if(!mysql_load_plugin(&amp;mysql, "myplugin",
                      MYSQL_CLIENT_AUTHENTICATION_PLUGIN, 0))
{
    fprintf(stderr, "Error: %s\n", mysql_error(&amp;mysql));
    exit(-1);
}
</pre>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-load-plugin-see-also"></a>See Also</h5>

</div>

</div>

</div>
<p>
          See also <a class="xref" href="connectors-apis.html#mysql-load-plugin" title="27.8.14.3 mysql_load_plugin()">Section 27.8.14.3, “mysql_load_plugin()”</a>,
          <a class="xref" href="connectors-apis.html#mysql-error" title="27.8.7.15 mysql_error()">Section 27.8.7.15, “mysql_error()”</a>, <a class="xref" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()">Section 27.8.7.14, “mysql_errno()”</a>.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-load-plugin-v"></a>27.8.14.4 mysql_load_plugin_v()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571112992"></a><p>
        <code class="literal">struct st_mysql_client_plugin
        *mysql_load_plugin_v(MYSQL *mysql, const char *name, int type,
        int argc, va_list args)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-load-plugin-v-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          This function is equivalent to
          <a class="link" href="connectors-apis.html#mysql-load-plugin" title="27.8.14.3 mysql_load_plugin()"><code class="literal">mysql_load_plugin()</code></a>, but it
          accepts a <code class="literal">va_list</code> instead of a variable
          list of parameters.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-load-plugin-v-see-also"></a>See Also</h5>

</div>

</div>

</div>
<p>
          See also <a class="xref" href="connectors-apis.html#mysql-load-plugin" title="27.8.14.3 mysql_load_plugin()">Section 27.8.14.3, “mysql_load_plugin()”</a>.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-plugin-options"></a>27.8.14.5 mysql_plugin_options()</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710571103392"></a><p>
        <code class="literal">int mysql_plugin_options(struct st_mysql_client_plugin
        *plugin, const char *option, const void *value)</code>
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="mysql-plugin-options-description"></a>Description</h5>
</div>
</div>
</div>
<p>
          Passes an option type and value to a plugin. This function can
          be called multiple times to set several options. If the plugin
          does not have an option handler, an error occurs.
        </p><p>
          Specify the parameters as follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <code class="literal">plugin</code>: A pointer to the plugin
              structure.
            </p></li><li class="listitem"><p>
              <code class="literal">option</code>: The option to be set.
            </p></li><li class="listitem"><p>
              <code class="literal">value</code>: A pointer to the option value.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-plugin-options-return-values"></a>Return Values</h5>

</div>

</div>

</div>
<p>
          Zero for success, 1 if an error occurred. If the plugin has an
          option handler, that handler should also return zero for
          success and 1 if an error occurred.
</p>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="c-api-encrypted-connections"></a>27.8.15 C API Encrypted Connection Support</h3>

</div>

</div>

</div>
<p>
      This section describes how C applications use the C API
      capabilities for encrypted connections. By default, MySQL programs
      attempt to connect using encryption if the server supports
      encrypted connections, falling back to an unencrypted connection
      if an encrypted connection cannot be established (see
      <a class="xref" href="security.html#using-encrypted-connections" title="6.4.1 Configuring MySQL to Use Encrypted Connections">Section 6.4.1, “Configuring MySQL to Use Encrypted Connections”</a>). For applications
      that require control beyond the default behavior over how
      encrypted connections are established, the C API provides these
      capabilities:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          The <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> function
          enables applications to set the appropriate SSL/TLS options
          before calling
          <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a>. For
          example, to require the use of an encrypted connection, see
          <a class="xref" href="connectors-apis.html#c-api-enforcing-encrypted-connection" title="Enforcing an Encrypted Connection">Enforcing an Encrypted Connection</a>.
        </p></li><li class="listitem"><p>
          The <a class="link" href="connectors-apis.html#mysql-get-ssl-cipher" title="27.8.7.34 mysql_get_ssl_cipher()"><code class="literal">mysql_get_ssl_cipher()</code></a>
          function enables applications to determine, after a connection
          has been established, whether the connection uses encryption.
          A <code class="literal">NULL</code> return value indicates that
          encryption is not being used. A non-<code class="literal">NULL</code>
          return value indicates an encrypted connection and names the
          encryption cipher. See <a class="xref" href="connectors-apis.html#mysql-get-ssl-cipher" title="27.8.7.34 mysql_get_ssl_cipher()">Section 27.8.7.34, “mysql_get_ssl_cipher()”</a>.
</p></li></ul>
</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="connectors-apis.html#c-api-encrypted-connection-options" title="C API Options for Encrypted Connections">C API Options for Encrypted Connections</a></p></li><li class="listitem"><p><a class="xref" href="connectors-apis.html#c-api-enforcing-encrypted-connection" title="Enforcing an Encrypted Connection">Enforcing an Encrypted Connection</a></p></li><li class="listitem"><p><a class="xref" href="connectors-apis.html#c-api-secure-encrypted-connection" title="Improving Security of Encrypted Connections">Improving Security of Encrypted Connections</a></p></li></ul>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="c-api-encrypted-connection-options"></a>C API Options for Encrypted Connections</h4>

</div>

</div>

</div>
<p>
        <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> provides the
        following options for control over use of encrypted connections.
        For option details, see <a class="xref" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()">Section 27.8.7.50, “mysql_options()”</a>.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">MYSQL_OPT_SSL_CA</code>: The path name of the
            Certificate Authority (CA) certificate file. This option, if
            used, must specify the same certificate used by the server.
          </p></li><li class="listitem"><p>
            <code class="literal">MYSQL_OPT_SSL_CAPATH</code>: The path name of
            the directory that contains trusted SSL CA certificate
            files.
          </p></li><li class="listitem"><p>
            <code class="literal">MYSQL_OPT_SSL_CERT</code>: The path name of the
            client public key certificate file.
          </p></li><li class="listitem"><p>
            <code class="literal">MYSQL_OPT_SSL_CIPHER</code>: The list of
            permitted ciphers for SSL encryption.
          </p></li><li class="listitem"><p>
            <code class="literal">MYSQL_OPT_SSL_CRL</code>: The path name of the
            file containing certificate revocation lists.
          </p></li><li class="listitem"><p>
            <code class="literal">MYSQL_OPT_SSL_CRLPATH</code>: The path name of
            the directory that contains certificate revocation list
            files.
          </p></li><li class="listitem"><p>
            <code class="literal">MYSQL_OPT_SSL_KEY</code>: The path name of the
            client private key file.
          </p></li><li class="listitem"><p>
            <code class="literal">MYSQL_OPT_SSL_MODE</code>: The connection
            security state.
          </p></li><li class="listitem"><p>
            <code class="literal">MYSQL_OPT_SSL_VERIFY_SERVER_CERT</code>: Whether
            to perform host name identity verification of the server
            certificate Common Name value.
          </p></li><li class="listitem"><p>
            <code class="literal">MYSQL_OPT_TLS_VERSION</code>: The encryption
            protocols permitted by the client.
</p></li></ul>
</div>
<p>
        <a class="link" href="connectors-apis.html#mysql-ssl-set" title="27.8.7.73 mysql_ssl_set()"><code class="literal">mysql_ssl_set()</code></a> can be used as a
        convenience routine that is equivalent to a set of
        <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> calls that
        specify certificate and key files, encryption ciphers, and so
        forth. See <a class="xref" href="connectors-apis.html#mysql-ssl-set" title="27.8.7.73 mysql_ssl_set()">Section 27.8.7.73, “mysql_ssl_set()”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="c-api-enforcing-encrypted-connection"></a>Enforcing an Encrypted Connection</h4>

</div>

</div>

</div>
<p>
        <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> options for
        information such as SSL certificate and key files are used to
        establish an encrypted connection if such connections are
        available, but do not enforce any requirement that the
        connection obtained be encrypted. To require an encrypted
        connection, use the following technique:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
            Call <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> as
            necessary supply the appropriate SSL parameters (certificate
            and key files, encryption ciphers, and so forth).
          </p></li><li class="listitem"><p>
            Call <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> to pass
            the <code class="literal">MYSQL_OPT_SSL_MODE</code> option with a
            value of <code class="literal">SSL_MODE_REQUIRED</code> or one of the
            more-restrictive option values.
          </p></li><li class="listitem"><p>
            Call <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a> to
            connect to the server. The call fails if an encrypted
            connection cannot be obtained; exit with an error.
</p></li></ol>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="c-api-secure-encrypted-connection"></a>Improving Security of Encrypted Connections</h4>

</div>

</div>

</div>
<p>
        For additional security relative to that provided by the default
        encryption, clients can supply a CA certificate matching the one
        used by the server and enable host name identity verification.
        In this way, the server and client place their trust in the same
        CA certificate and the client verifies that the host to which it
        connected is the one intended:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            To specify the CA certificate, call
            <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> to pass the
            <code class="literal">MYSQL_OPT_SSL_CA</code> (or
            <code class="literal">MYSQL_OPT_SSL_CAPATH</code>) option, and call
            <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> to pass the
            <code class="literal">MYSQL_OPT_SSL_MODE</code> option with a value of
            <code class="literal">SSL_MODE_VERIFY_CA</code>.
          </p></li><li class="listitem"><p>
            To enable host name identity verification as well, call
            <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> to pass the
            <code class="literal">MYSQL_OPT_SSL_MODE</code> option with a value of
            <code class="literal">SSL_MODE_VERIFY_IDENTITY</code> rather than
            <code class="literal">SSL_MODE_VERIFY_CA</code>.
</p></li></ul>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<div class="admon-title">
Note
</div>
<p>
          Host name identity verification does not work with self-signed
          certificates created automatically by the server, or manually
          using <a class="link" href="programs.html#mysql-ssl-rsa-setup" title="4.4.5 mysql_ssl_rsa_setup — Create SSL/RSA Files"><span class="command"><strong>mysql_ssl_rsa_setup</strong></span></a> (see
          <a class="xref" href="security.html#creating-ssl-rsa-files-using-mysql" title="6.4.3.1 Creating SSL and RSA Certificates and Keys using MySQL">Section 6.4.3.1, “Creating SSL and RSA Certificates and Keys using MySQL”</a>). Such
          self-signed certificates do not contain the server name as the
          Common Name value.
</p>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="c-api-multiple-queries"></a>27.8.16 C API Multiple Statement Execution Support</h3>

</div>

</div>

</div>
<p>
      By default, <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a> and
      <a class="link" href="connectors-apis.html#mysql-real-query" title="27.8.7.57 mysql_real_query()"><code class="literal">mysql_real_query()</code></a> interpret their
      statement string argument as a single statement to be executed,
      and you process the result according to whether the statement
      produces a result set (a set of rows, as for
      <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a>) or an affected-rows count
      (as for <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT</code></a>,
      <a class="link" href="sql-syntax.html#update" title="13.2.11 UPDATE Syntax"><code class="literal">UPDATE</code></a>, and so forth).
    </p><p>
      MySQL also supports the execution of a string containing multiple
      statements separated by semicolon (<code class="literal">;</code>)
      characters. This capability is enabled by special options that are
      specified either when you connect to the server with
      <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a> or after
      connecting by calling
      <a class="link" href="connectors-apis.html#mysql-set-server-option" title="27.8.7.70 mysql_set_server_option()"><code class="literal">mysql_set_server_option()</code></a>.
    </p><p>
      Executing a multiple-statement string can produce multiple result
      sets or row-count indicators. Processing these results involves a
      different approach than for the single-statement case: After
      handling the result from the first statement, it is necessary to
      check whether more results exist and process them in turn if so.
      To support multiple-result processing, the C API includes the
      <a class="link" href="connectors-apis.html#mysql-more-results" title="27.8.7.46 mysql_more_results()"><code class="literal">mysql_more_results()</code></a> and
      <a class="link" href="connectors-apis.html#mysql-next-result" title="27.8.7.47 mysql_next_result()"><code class="literal">mysql_next_result()</code></a> functions.
      These functions are used at the end of a loop that iterates as
      long as more results are available. <span class="emphasis"><em>Failure to process
      the result this way may result in a dropped connection to the
      server.</em></span>
    </p><p>
      Multiple-result processing also is required if you execute
      <a class="link" href="sql-syntax.html#call" title="13.2.1 CALL Syntax"><code class="literal">CALL</code></a> statements for stored
      procedures. Results from a stored procedure have these
      characteristics:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          Statements within the procedure may produce result sets (for
          example, if it executes <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a>
          statements). These result sets are returned in the order that
          they are produced as the procedure executes.
        </p><p>
          In general, the caller cannot know how many result sets a
          procedure will return. Procedure execution may depend on loops
          or conditional statements that cause the execution path to
          differ from one call to the next. Therefore, you must be
          prepared to retrieve multiple results.
        </p></li><li class="listitem"><p>
          The final result from the procedure is a status result that
          includes no result set. The status indicates whether the
          procedure succeeded or an error occurred.
</p></li></ul>
</div>
<p>
      The multiple statement and result capabilities can be used only
      with <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a> or
      <a class="link" href="connectors-apis.html#mysql-real-query" title="27.8.7.57 mysql_real_query()"><code class="literal">mysql_real_query()</code></a>. They cannot be
      used with the prepared statement interface. Prepared statement
      handlers are defined to work only with strings that contain a
      single statement. See <a class="xref" href="connectors-apis.html#c-api-prepared-statements" title="27.8.8 C API Prepared Statements">Section 27.8.8, “C API Prepared Statements”</a>.
    </p><p>
      To enable multiple-statement execution and result processing, the
      following options may be used:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          The <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a>
          function has a <code class="literal">flags</code> argument for which two
          option values are relevant:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
              <code class="literal">CLIENT_MULTI_RESULTS</code> enables the client
              program to process multiple results. This option
              <span class="emphasis"><em>must</em></span> be enabled if you execute
              <a class="link" href="sql-syntax.html#call" title="13.2.1 CALL Syntax"><code class="literal">CALL</code></a> statements for stored
              procedures that produce result sets. Otherwise, such
              procedures result in an error <code class="literal">Error 1312 (0A000):
              PROCEDURE <em class="replaceable"><code>proc_name</code></em> can't
              return a result set in the given context</code>. In
              MySQL 5.7,
              <code class="literal">CLIENT_MULTI_RESULTS</code> is enabled by
              default.
            </p></li><li class="listitem"><p>
              <code class="literal">CLIENT_MULTI_STATEMENTS</code> enables
              <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a> and
              <a class="link" href="connectors-apis.html#mysql-real-query" title="27.8.7.57 mysql_real_query()"><code class="literal">mysql_real_query()</code></a> to
              execute statement strings containing multiple statements
              separated by semicolons. This option also enables
              <code class="literal">CLIENT_MULTI_RESULTS</code> implicitly, so a
              <code class="literal">flags</code> argument of
              <code class="literal">CLIENT_MULTI_STATEMENTS</code> to
              <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a> is
              equivalent to an argument of
              <code class="literal">CLIENT_MULTI_STATEMENTS |
              CLIENT_MULTI_RESULTS</code>. That is,
              <code class="literal">CLIENT_MULTI_STATEMENTS</code> is sufficient
              to enable multiple-statement execution and all
              multiple-result processing.
</p></li></ul>
</div>
</li><li class="listitem"><p>
          After the connection to the server has been established, you
          can use the
          <a class="link" href="connectors-apis.html#mysql-set-server-option" title="27.8.7.70 mysql_set_server_option()"><code class="literal">mysql_set_server_option()</code></a>
          function to enable or disable multiple-statement execution by
          passing it an argument of
          <code class="literal">MYSQL_OPTION_MULTI_STATEMENTS_ON</code> or
          <code class="literal">MYSQL_OPTION_MULTI_STATEMENTS_OFF</code>. Enabling
          multiple-statement execution with this function also enables
          processing of <span class="quote">“<span class="quote">simple</span>”</span> results for a
          multiple-statement string where each statement produces a
          single result, but is <span class="emphasis"><em>not</em></span> sufficient to
          permit processing of stored procedures that produce result
          sets.
</p></li></ul>
</div>
<p>
      The following procedure outlines a suggested strategy for handling
      multiple statements:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
          Pass <code class="literal">CLIENT_MULTI_STATEMENTS</code> to
          <a class="link" href="connectors-apis.html#mysql-real-connect" title="27.8.7.54 mysql_real_connect()"><code class="literal">mysql_real_connect()</code></a>, to fully
          enable multiple-statement execution and multiple-result
          processing.
        </p></li><li class="listitem"><p>
          After calling <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a> or
          <a class="link" href="connectors-apis.html#mysql-real-query" title="27.8.7.57 mysql_real_query()"><code class="literal">mysql_real_query()</code></a> and
          verifying that it succeeds, enter a loop within which you
          process statement results.
        </p></li><li class="listitem"><p>
          For each iteration of the loop, handle the current statement
          result, retrieving either a result set or an affected-rows
          count. If an error occurs, exit the loop.
        </p></li><li class="listitem"><p>
          At the end of the loop, call
          <a class="link" href="connectors-apis.html#mysql-next-result" title="27.8.7.47 mysql_next_result()"><code class="literal">mysql_next_result()</code></a> to check
          whether another result exists and initiate retrieval for it if
          so. If no more results are available, exit the loop.
</p></li></ol>
</div>
<p>
      One possible implementation of the preceding strategy is shown
      following. The final part of the loop can be reduced to a simple
      test of whether
      <a class="link" href="connectors-apis.html#mysql-next-result" title="27.8.7.47 mysql_next_result()"><code class="literal">mysql_next_result()</code></a> returns
      nonzero. The code as written distinguishes between no more results
      and an error, which enables a message to be printed for the latter
      occurrence.
    </p><pre data-lang="c" class="programlisting">
/* connect to server with the CLIENT_MULTI_STATEMENTS option */
if (mysql_real_connect (mysql, host_name, user_name, password,
    db_name, port_num, socket_name, CLIENT_MULTI_STATEMENTS) == NULL)
{
  printf("mysql_real_connect() failed\n");
  mysql_close(mysql);
  exit(1);
}

/* execute multiple statements */
status = mysql_query(mysql,
                     "DROP TABLE IF EXISTS test_table;\
                      CREATE TABLE test_table(id INT);\
                      INSERT INTO test_table VALUES(10);\
                      UPDATE test_table SET id=20 WHERE id=10;\
                      SELECT * FROM test_table;\
                      DROP TABLE test_table");
if (status)
{
  printf("Could not execute statement(s)");
  mysql_close(mysql);
  exit(0);
}

/* process each statement result */
do {
  /* did current statement return data? */
  result = mysql_store_result(mysql);
  if (result)
  {
    /* yes; process rows and free the result set */
    process_result_set(mysql, result);
    mysql_free_result(result);
  }
  else          /* no result set or error */
  {
    if (mysql_field_count(mysql) == 0)
    {
      printf("%lld rows affected\n",
            mysql_affected_rows(mysql));
    }
    else  /* some error occurred */
    {
      printf("Could not retrieve result set\n");
      break;
    }
  }
  /* more results? -1 = no, &gt;0 = error, 0 = yes (keep looping) */
  if ((status = mysql_next_result(mysql)) &gt; 0)
    printf("Could not execute statement\n");
} while (status == 0);

mysql_close(mysql);
</pre>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="c-api-prepared-statement-date-handling"></a>27.8.17 C API Prepared Statement Handling of Date and Time Values</h3>

</div>

</div>

</div>
<p>
      The binary (prepared statement) protocol enables you to send and
      receive date and time values (<a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">DATE</code></a>,
      <a class="link" href="data-types.html#time" title="11.3.2 The TIME Type"><code class="literal">TIME</code></a>,
      <a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">DATETIME</code></a>, and
      <a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">TIMESTAMP</code></a>), using the
      <code class="literal">MYSQL_TIME</code> structure. The members of this
      structure are described in
      <a class="xref" href="connectors-apis.html#c-api-prepared-statement-data-structures" title="27.8.9 C API Prepared Statement Data Structures">Section 27.8.9, “C API Prepared Statement Data Structures”</a>.
    </p><p>
      To send temporal data values, create a prepared statement using
      <a class="link" href="connectors-apis.html#mysql-stmt-prepare" title="27.8.11.21 mysql_stmt_prepare()"><code class="literal">mysql_stmt_prepare()</code></a>. Then, before
      calling <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a> to
      execute the statement, use the following procedure to set up each
      temporal parameter:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
          In the <code class="literal">MYSQL_BIND</code> structure associated with
          the data value, set the <code class="literal">buffer_type</code> member
          to the type that indicates what kind of temporal value you're
          sending. For <a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">DATE</code></a>,
          <a class="link" href="data-types.html#time" title="11.3.2 The TIME Type"><code class="literal">TIME</code></a>,
          <a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">DATETIME</code></a>, or
          <a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">TIMESTAMP</code></a> values, set
          <code class="literal">buffer_type</code> to
          <code class="literal">MYSQL_TYPE_DATE</code>,
          <code class="literal">MYSQL_TYPE_TIME</code>,
          <code class="literal">MYSQL_TYPE_DATETIME</code>, or
          <code class="literal">MYSQL_TYPE_TIMESTAMP</code>, respectively.
        </p></li><li class="listitem"><p>
          Set the <code class="literal">buffer</code> member of the
          <code class="literal">MYSQL_BIND</code> structure to the address of the
          <code class="literal">MYSQL_TIME</code> structure in which you pass the
          temporal value.
        </p></li><li class="listitem"><p>
          Fill in the members of the <code class="literal">MYSQL_TIME</code>
          structure that are appropriate for the type of temporal value
          to pass.
</p></li></ol>
</div>
<p>
      Use <a class="link" href="connectors-apis.html#mysql-stmt-bind-param" title="27.8.11.4 mysql_stmt_bind_param()"><code class="literal">mysql_stmt_bind_param()</code></a> to
      bind the parameter data to the statement. Then you can call
      <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a>.
    </p><p>
      To retrieve temporal values, the procedure is similar, except that
      you set the <code class="literal">buffer_type</code> member to the type of
      value you expect to receive, and the <code class="literal">buffer</code>
      member to the address of a <code class="literal">MYSQL_TIME</code> structure
      into which the returned value should be placed. Use
      <a class="link" href="connectors-apis.html#mysql-stmt-bind-result" title="27.8.11.5 mysql_stmt_bind_result()"><code class="literal">mysql_stmt_bind_result()</code></a> to bind
      the buffers to the statement after calling
      <a class="link" href="connectors-apis.html#mysql-stmt-execute" title="27.8.11.10 mysql_stmt_execute()"><code class="literal">mysql_stmt_execute()</code></a> and before
      fetching the results.
    </p><p>
      Here is a simple example that inserts
      <a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">DATE</code></a>,
      <a class="link" href="data-types.html#time" title="11.3.2 The TIME Type"><code class="literal">TIME</code></a>, and
      <a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">TIMESTAMP</code></a> data. The
      <code class="literal">mysql</code> variable is assumed to be a valid
      connection handler.
    </p><pre data-lang="c" class="programlisting">

  MYSQL_TIME  ts;
  MYSQL_BIND  bind[3];
  MYSQL_STMT  *stmt;

  strmov(query, "INSERT INTO test_table(date_field, time_field, \
                               timestamp_field) VALUES(?,?,?");

  stmt = mysql_stmt_init(mysql);
  if (!stmt)
  {
    fprintf(stderr, " mysql_stmt_init(), out of memory\n");
    exit(0);
  }
  if (mysql_stmt_prepare(mysql, query, strlen(query)))
  {
    fprintf(stderr, "\n mysql_stmt_prepare(), INSERT failed");
    fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
    exit(0);
  }

  /* set up input buffers for all 3 parameters */
  bind[0].buffer_type= MYSQL_TYPE_DATE;
  bind[0].buffer= (char *)&amp;ts;
  bind[0].is_null= 0;
  bind[0].length= 0;
  ...
  bind[1]= bind[2]= bind[0];
  ...

  mysql_stmt_bind_param(stmt, bind);

  /* supply the data to be sent in the ts structure */
  ts.year= 2002;
  ts.month= 02;
  ts.day= 03;

  ts.hour= 10;
  ts.minute= 45;
  ts.second= 20;

  mysql_stmt_execute(stmt);
  ..

</pre>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="c-api-prepared-call-statements"></a>27.8.18 C API Prepared CALL Statement Support</h3>

</div>

</div>

</div>
<p>
      This section describes prepared-statement support in the C API for
      stored procedures executed using
      <a class="link" href="sql-syntax.html#call" title="13.2.1 CALL Syntax"><code class="literal">CALL</code></a> statements:
    </p><p>
      Stored procedures executed using prepared
      <a class="link" href="sql-syntax.html#call" title="13.2.1 CALL Syntax"><code class="literal">CALL</code></a> statements can be used in the
      following ways:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          A stored procedure can produce any number of result sets. The
          number of columns and the data types of the columns need not
          be the same for all result sets.
        </p></li><li class="listitem"><p>
          The final values of <code class="literal">OUT</code> and
          <code class="literal">INOUT</code> parameters are available to the
          calling application after the procedure returns. These
          parameters are returned as an extra single-row result set
          following any result sets produced by the procedure itself.
          The row contains the values of the <code class="literal">OUT</code> and
          <code class="literal">INOUT</code> parameters in the order in which they
          are declared in the procedure parameter list.
</p></li></ul>
</div>
<p>
      The following discussion shows how to use these capabilities
      through the C API for prepared statements. To use prepared
      <a class="link" href="sql-syntax.html#call" title="13.2.1 CALL Syntax"><code class="literal">CALL</code></a> statements through the
      <a class="link" href="sql-syntax.html#prepare" title="13.5.1 PREPARE Syntax"><code class="literal">PREPARE</code></a> and
      <a class="link" href="sql-syntax.html#execute" title="13.5.2 EXECUTE Syntax"><code class="literal">EXECUTE</code></a> statements, see
      <a class="xref" href="sql-syntax.html#call" title="13.2.1 CALL Syntax">Section 13.2.1, “CALL Syntax”</a>.
    </p><p>
      An application that executes a prepared
      <a class="link" href="sql-syntax.html#call" title="13.2.1 CALL Syntax"><code class="literal">CALL</code></a> statement should use a loop
      that fetches a result and then invokes
      <a class="link" href="connectors-apis.html#mysql-stmt-next-result" title="27.8.11.17 mysql_stmt_next_result()"><code class="literal">mysql_stmt_next_result()</code></a> to
      determine whether there are more results. The results consist of
      any result sets produced by the stored procedure followed by a
      final status value that indicates whether the procedure terminated
      successfully.
    </p><p>
      If the procedure has <code class="literal">OUT</code> or
      <code class="literal">INOUT</code> parameters, the result set preceding the
      final status value contains their values. To determine whether a
      result set contains parameter values, test whether the
      <code class="literal">SERVER_PS_OUT_PARAMS</code> bit is set in the
      <code class="literal">server_status</code> member of the
      <code class="literal">MYSQL</code> connection handler:
    </p><pre data-lang="c" class="programlisting">
mysql-&gt;server_status &amp; SERVER_PS_OUT_PARAMS
</pre><p>
      The following example uses a prepared
      <a class="link" href="sql-syntax.html#call" title="13.2.1 CALL Syntax"><code class="literal">CALL</code></a> statement to execute a stored
      procedure that produces multiple result sets and that provides
      parameter values back to the caller by means of
      <code class="literal">OUT</code> and <code class="literal">INOUT</code> parameters.
      The procedure takes parameters of all three types
      (<code class="literal">IN</code>, <code class="literal">OUT</code>,
      <code class="literal">INOUT</code>), displays their initial values, assigns
      new values, displays the updated values, and returns. The expected
      return information from the procedure therefore consists of
      multiple result sets and a final status:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          One result set from a <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a>
          that displays the initial parameter values:
          <code class="literal">10</code>, <code class="literal">NULL</code>,
          <code class="literal">30</code>. (The <code class="literal">OUT</code> parameter
          is assigned a value by the caller, but this assignment is
          expected to be ineffective: <code class="literal">OUT</code> parameters
          are seen as <code class="literal">NULL</code> within a procedure until
          assigned a value within the procedure.)
        </p></li><li class="listitem"><p>
          One result set from a <a class="link" href="sql-syntax.html#select" title="13.2.9 SELECT Syntax"><code class="literal">SELECT</code></a>
          that displays the modified parameter values:
          <code class="literal">100</code>, <code class="literal">200</code>,
          <code class="literal">300</code>.
        </p></li><li class="listitem"><p>
          One result set containing the final <code class="literal">OUT</code> and
          <code class="literal">INOUT</code> parameter values:
          <code class="literal">200</code>, <code class="literal">300</code>.
        </p></li><li class="listitem"><p>
          A final status packet.
</p></li></ul>
</div>
<p>
      The code to execute the procedure:
    </p><pre data-lang="c" class="programlisting">
MYSQL_STMT *stmt;
MYSQL_BIND ps_params[3];  /* input parameter buffers */
int        int_data[3];   /* input/output values */
my_bool    is_null[3];    /* output value nullability */
int        status;

/* set up stored procedure */
status = mysql_query(mysql, "DROP PROCEDURE IF EXISTS p1");
test_error(mysql, status);

status = mysql_query(mysql,
  "CREATE PROCEDURE p1("
  "  IN p_in INT, "
  "  OUT p_out INT, "
  "  INOUT p_inout INT) "
  "BEGIN "
  "  SELECT p_in, p_out, p_inout; "
  "  SET p_in = 100, p_out = 200, p_inout = 300; "
  "  SELECT p_in, p_out, p_inout; "
  "END");
test_error(mysql, status);

/* initialize and prepare CALL statement with parameter placeholders */
stmt = mysql_stmt_init(mysql);
if (!stmt)
{
  printf("Could not initialize statement\n");
  exit(1);
}
status = mysql_stmt_prepare(stmt, "CALL p1(?, ?, ?)", 16);
test_stmt_error(stmt, status);

/* initialize parameters: p_in, p_out, p_inout (all INT) */
memset(ps_params, 0, sizeof (ps_params));

ps_params[0].buffer_type = MYSQL_TYPE_LONG;
ps_params[0].buffer = (char *) &amp;int_data[0];
ps_params[0].length = 0;
ps_params[0].is_null = 0;

ps_params[1].buffer_type = MYSQL_TYPE_LONG;
ps_params[1].buffer = (char *) &amp;int_data[1];
ps_params[1].length = 0;
ps_params[1].is_null = 0;

ps_params[2].buffer_type = MYSQL_TYPE_LONG;
ps_params[2].buffer = (char *) &amp;int_data[2];
ps_params[2].length = 0;
ps_params[2].is_null = 0;

/* bind parameters */
status = mysql_stmt_bind_param(stmt, ps_params);
test_stmt_error(stmt, status);

/* assign values to parameters and execute statement */
int_data[0]= 10;  /* p_in */
int_data[1]= 20;  /* p_out */
int_data[2]= 30;  /* p_inout */

status = mysql_stmt_execute(stmt);
test_stmt_error(stmt, status);

/* process results until there are no more */
do {
  int i;
  int num_fields;       /* number of columns in result */
  MYSQL_FIELD *fields;  /* for result set metadata */
  MYSQL_BIND *rs_bind;  /* for output buffers */

  /* the column count is &gt; 0 if there is a result set */
  /* 0 if the result is only the final status packet */
  num_fields = mysql_stmt_field_count(stmt);

  if (num_fields &gt; 0)
  {
    /* there is a result set to fetch */
    printf("Number of columns in result: %d\n", (int) num_fields);

    /* what kind of result set is this? */
    printf("Data: ");
    if(mysql-&gt;server_status &amp; SERVER_PS_OUT_PARAMS)
      printf("this result set contains OUT/INOUT parameters\n");
    else
      printf("this result set is produced by the procedure\n");

    MYSQL_RES *rs_metadata = mysql_stmt_result_metadata(stmt);
    test_stmt_error(stmt, rs_metadata == NULL);

    fields = mysql_fetch_fields(rs_metadata);

    rs_bind = (MYSQL_BIND *) malloc(sizeof (MYSQL_BIND) * num_fields);
    if (!rs_bind)
    {
      printf("Cannot allocate output buffers\n");
      exit(1);
    }
    memset(rs_bind, 0, sizeof (MYSQL_BIND) * num_fields);

    /* set up and bind result set output buffers */
    for (i = 0; i &lt; num_fields; ++i)
    {
      rs_bind[i].buffer_type = fields[i].type;
      rs_bind[i].is_null = &amp;is_null[i];

      switch (fields[i].type)
      {
        case MYSQL_TYPE_LONG:
          rs_bind[i].buffer = (char *) &amp;(int_data[i]);
          rs_bind[i].buffer_length = sizeof (int_data);
          break;

        default:
          fprintf(stderr, "ERROR: unexpected type: %d.\n", fields[i].type);
          exit(1);
      }
    }

    status = mysql_stmt_bind_result(stmt, rs_bind);
    test_stmt_error(stmt, status);

    /* fetch and display result set rows */
    while (1)
    {
      status = mysql_stmt_fetch(stmt);

      if (status == 1 || status == MYSQL_NO_DATA)
        break;

      for (i = 0; i &lt; num_fields; ++i)
      {
        switch (rs_bind[i].buffer_type)
        {
          case MYSQL_TYPE_LONG:
            if (*rs_bind[i].is_null)
              printf(" val[%d] = NULL;", i);
            else
              printf(" val[%d] = %ld;",
                     i, (long) *((int *) rs_bind[i].buffer));
            break;

          default:
            printf("  unexpected type (%d)\n",
              rs_bind[i].buffer_type);
        }
      }
      printf("\n");
    }

    mysql_free_result(rs_metadata); /* free metadata */
    free(rs_bind);                  /* free output buffers */
  }
  else
  {
    /* no columns = final status packet */
    printf("End of procedure output\n");
  }

  /* more results? -1 = no, &gt;0 = error, 0 = yes (keep looking) */
  status = mysql_stmt_next_result(stmt);
  if (status &gt; 0)
    test_stmt_error(stmt, status);
} while (status == 0);

mysql_stmt_close(stmt);
</pre><p>
      Execution of the procedure should produce the following output:
    </p><pre data-lang="c" class="programlisting">
Number of columns in result: 3
Data: this result set is produced by the procedure
 val[0] = 10; val[1] = NULL; val[2] = 30;
Number of columns in result: 3
Data: this result set is produced by the procedure
 val[0] = 100; val[1] = 200; val[2] = 300;
Number of columns in result: 2
Data: this result set contains OUT/INOUT parameters
 val[0] = 200; val[1] = 300;
End of procedure output
</pre><p>
      The code uses two utility routines,
      <code class="literal">test_error()</code> and
      <code class="literal">test_stmt_error()</code>, to check for errors and
      terminate after printing diagnostic information if an error
      occurred:
    </p><pre data-lang="c" class="programlisting">
static void test_error(MYSQL *mysql, int status)
{
  if (status)
  {
    fprintf(stderr, "Error: %s (errno: %d)\n",
            mysql_error(mysql), mysql_errno(mysql));
    exit(1);
  }
}

static void test_stmt_error(MYSQL_STMT *stmt, int status)
{
  if (status)
  {
    fprintf(stderr, "Error: %s (errno: %d)\n",
            mysql_stmt_error(stmt), mysql_stmt_errno(stmt));
    exit(1);
  }
}
</pre>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="c-api-prepared-statement-problems"></a>27.8.19 C API Prepared Statement Problems</h3>

</div>

</div>

</div>
<p>
      Here follows a list of the currently known problems with prepared
      statements:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <a class="link" href="data-types.html#time" title="11.3.2 The TIME Type"><code class="literal">TIME</code></a>,
          <a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">TIMESTAMP</code></a>, and
          <a class="link" href="data-types.html#datetime" title="11.3.1 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">DATETIME</code></a> do not support parts
          of seconds (for example, from
          <a class="link" href="functions.html#function_date-format"><code class="literal">DATE_FORMAT()</code></a>).
        </p></li><li class="listitem"><p>
          <a class="indexterm" name="idm140710570847760"></a>

          When converting an integer to string,
          <code class="literal">ZEROFILL</code> is honored with prepared
          statements in some cases where the MySQL server does not print
          the leading zeros. (For example, with
          <a class="link" href="functions.html#function_min"><code class="literal">MIN(<em class="replaceable"><code>number-with-zerofill</code></em>)</code></a>).
        </p></li><li class="listitem"><p>
          When converting a floating-point number to a string in the
          client, the rightmost digits of the converted value may differ
          slightly from those of the original value.
        </p></li><li class="listitem"><p>
          Prepared statements use the query cache under the conditions
          described in <a class="xref" href="optimization.html#query-cache-operation" title="8.10.3.1 How the Query Cache Operates">Section 8.10.3.1, “How the Query Cache Operates”</a>.
        </p></li><li class="listitem"><p>
          Prepared statements do not support multi-statements (that is,
          multiple statements within a single string separated by
          <code class="literal">;</code> characters).
        </p></li><li class="listitem"><p>
          The capabilities of prepared
          <a class="link" href="sql-syntax.html#call" title="13.2.1 CALL Syntax"><code class="literal">CALL</code></a> statements are described
          in <a class="xref" href="connectors-apis.html#c-api-prepared-call-statements" title="27.8.18 C API Prepared CALL Statement Support">Section 27.8.18, “C API Prepared CALL Statement Support”</a>.
</p></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="c-api-auto-reconnect"></a>27.8.20 C API Automatic Reconnection Control</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140710570835552"></a><p>
      The MySQL client library can perform an automatic reconnection to
      the server if it finds that the connection is down when you
      attempt to send a statement to the server to be executed. If
      auto-reconnect is enabled, the library tries once to reconnect to
      the server and send the statement again.
    </p><p>
      Auto-reconnect is disabled by default.
    </p><p>
      If it is important for your application to know that the
      connection has been dropped (so that it can exit or take action to
      adjust for the loss of state information), be sure that
      auto-reconnect is disabled. To ensure this, call
      <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> with the
      <code class="literal">MYSQL_OPT_RECONNECT</code> option:
    </p><pre data-lang="c" class="programlisting">
my_bool reconnect = 0;
mysql_options(&amp;mysql, MYSQL_OPT_RECONNECT, &amp;reconnect);
</pre><p>
      If the connection has gone down, the effect of
      <a class="link" href="connectors-apis.html#mysql-ping" title="27.8.7.52 mysql_ping()"><code class="literal">mysql_ping()</code></a> depends on the
      auto-reconnect state. If auto-reconnect is enabled,
      <a class="link" href="connectors-apis.html#mysql-ping" title="27.8.7.52 mysql_ping()"><code class="literal">mysql_ping()</code></a> performs a reconnect.
      Otherwise, it returns an error.
    </p><p>
      Some client programs might provide the capability of controlling
      automatic reconnection. For example, <a class="link" href="programs.html#mysql" title="4.5.1 mysql — The MySQL Command-Line Tool"><span class="command"><strong>mysql</strong></span></a>
      reconnects by default, but the
      <a class="link" href="programs.html#option_mysql_reconnect"><code class="option">--skip-reconnect</code></a>
      option can be used to suppress this behavior.
    </p><p>
      If an automatic reconnection does occur (for example, as a result
      of calling <a class="link" href="connectors-apis.html#mysql-ping" title="27.8.7.52 mysql_ping()"><code class="literal">mysql_ping()</code></a>), there is
      no explicit indication of it. To check for reconnection, call
      <a class="link" href="connectors-apis.html#mysql-thread-id" title="27.8.7.76 mysql_thread_id()"><code class="literal">mysql_thread_id()</code></a> to get the
      original connection identifier before calling
      <a class="link" href="connectors-apis.html#mysql-ping" title="27.8.7.52 mysql_ping()"><code class="literal">mysql_ping()</code></a>, then call
      <a class="link" href="connectors-apis.html#mysql-thread-id" title="27.8.7.76 mysql_thread_id()"><code class="literal">mysql_thread_id()</code></a> again to see
      whether the identifier changed.
    </p><p>
      Automatic reconnection can be convenient because you need not
      implement your own reconnect code, but if a reconnection does
      occur, several aspects of the connection state are reset on the
      server side and your application will not be notified.
    </p><p>
      The connection-related state is affected as follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          Any active transactions are rolled back and autocommit mode is
          reset.
        </p></li><li class="listitem"><p>
          All table locks are released.
        </p></li><li class="listitem"><p>
          All <code class="literal">TEMPORARY</code> tables are closed (and
          dropped).
        </p></li><li class="listitem"><p>
          Session system variables are reinitialized to the values of
          the corresponding global system variables, including system
          variables that are set implicitly by statements such as
          <a class="link" href="sql-syntax.html#set-names" title="13.7.4.3 SET NAMES Syntax"><code class="literal">SET NAMES</code></a>.
        </p></li><li class="listitem"><p>
          User variable settings are lost.
        </p></li><li class="listitem"><p>
          Prepared statements are released.
        </p></li><li class="listitem"><p>
          <a class="link" href="sql-syntax.html#handler" title="13.2.4 HANDLER Syntax"><code class="literal">HANDLER</code></a> variables are closed.
        </p></li><li class="listitem"><p>
          The value of <a class="link" href="functions.html#function_last-insert-id"><code class="literal">LAST_INSERT_ID()</code></a>
          is reset to 0.
        </p></li><li class="listitem"><p>
          Locks acquired with <a class="link" href="functions.html#function_get-lock"><code class="literal">GET_LOCK()</code></a>
          are released.
        </p></li><li class="listitem"><p>
          The association of the client with the Performance Schema
          <a class="link" href="performance-schema.html#threads-table" title="25.11.16.3 The threads Table"><code class="literal">threads</code></a> table row that determines
          connection thread instrumentation is lost. If the client
          reconnects after a disconnect, the session is associated with
          a new row in the <a class="link" href="performance-schema.html#threads-table" title="25.11.16.3 The threads Table"><code class="literal">threads</code></a> table
          and the thread monitoring state may be different. See
          <a class="xref" href="performance-schema.html#threads-table" title="25.11.16.3 The threads Table">Section 25.11.16.3, “The threads Table”</a>.
</p></li></ul>
</div>
<p>
      If reconnection occurs, any SQL statement specified by calling
      <a class="link" href="connectors-apis.html#mysql-options" title="27.8.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> with the
      <code class="literal">MYSQL_INIT_COMMAND</code> option is re-executed.
    </p><p>
      If the connection drops, it is possible that the session
      associated with the connection on the server side will still be
      running if the server has not yet detected that the client is no
      longer connected. In this case, any locks held by the original
      connection still belong to that session, so you may want to kill
      it by calling <a class="link" href="connectors-apis.html#mysql-kill" title="27.8.7.39 mysql_kill()"><code class="literal">mysql_kill()</code></a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="c-api-common-issues"></a>27.8.21 C API Common Issues</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="connectors-apis.html#null-mysql-store-result">27.8.21.1 Why mysql_store_result() Sometimes Returns NULL After mysql_query()
Returns Success</a></span></dt><dt><span class="section"><a href="connectors-apis.html#query-results">27.8.21.2 What Results You Can Get from a Query</a></span></dt><dt><span class="section"><a href="connectors-apis.html#getting-unique-id">27.8.21.3 How to Get the Unique ID for the Last Inserted Row</a></span></dt></dl>
</div>
<a class="indexterm" name="idm140710570792256"></a><a class="indexterm" name="idm140710570790768"></a>
<div class="section">

<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="null-mysql-store-result"></a>27.8.21.1 Why mysql_store_result() Sometimes Returns NULL After mysql_query()
Returns Success</h4>
</div>
</div>
</div>
<a class="indexterm" name="idm140710570788064"></a><a class="indexterm" name="idm140710570787024"></a><p>
        It is possible for
        <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a> to return
        <code class="literal">NULL</code> following a successful call to
        <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a>. When this
        happens, it means one of the following conditions occurred:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            There was a <code class="literal">malloc()</code> failure (for
            example, if the result set was too large).
          </p></li><li class="listitem"><p>
            The data could not be read (an error occurred on the
            connection).
          </p></li><li class="listitem"><p>
            The query returned no data (for example, it was an
            <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT</code></a>,
            <a class="link" href="sql-syntax.html#update" title="13.2.11 UPDATE Syntax"><code class="literal">UPDATE</code></a>, or
            <a class="link" href="sql-syntax.html#delete" title="13.2.2 DELETE Syntax"><code class="literal">DELETE</code></a>).
</p></li></ul>
</div>
<p>
        You can always check whether the statement should have produced
        a nonempty result by calling
        <a class="link" href="connectors-apis.html#mysql-field-count" title="27.8.7.22 mysql_field_count()"><code class="literal">mysql_field_count()</code></a>. If
        <a class="link" href="connectors-apis.html#mysql-field-count" title="27.8.7.22 mysql_field_count()"><code class="literal">mysql_field_count()</code></a> returns
        zero, the result is empty and the last query was a statement
        that does not return values (for example, an
        <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT</code></a> or a
        <a class="link" href="sql-syntax.html#delete" title="13.2.2 DELETE Syntax"><code class="literal">DELETE</code></a>). If
        <a class="link" href="connectors-apis.html#mysql-field-count" title="27.8.7.22 mysql_field_count()"><code class="literal">mysql_field_count()</code></a> returns a
        nonzero value, the statement should have produced a nonempty
        result. See the description of the
        <a class="link" href="connectors-apis.html#mysql-field-count" title="27.8.7.22 mysql_field_count()"><code class="literal">mysql_field_count()</code></a> function for
        an example.
      </p><p>
        You can test for an error by calling
        <a class="link" href="connectors-apis.html#mysql-error" title="27.8.7.15 mysql_error()"><code class="literal">mysql_error()</code></a> or
        <a class="link" href="connectors-apis.html#mysql-errno" title="27.8.7.14 mysql_errno()"><code class="literal">mysql_errno()</code></a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="query-results"></a>27.8.21.2 What Results You Can Get from a Query</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710570762464"></a><a class="indexterm" name="idm140710570761424"></a><a class="indexterm" name="idm140710570760352"></a><a class="indexterm" name="idm140710570759280"></a><p>
        In addition to the result set returned by a query, you can also
        get the following information:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <a class="link" href="connectors-apis.html#mysql-affected-rows" title="27.8.7.1 mysql_affected_rows()"><code class="literal">mysql_affected_rows()</code></a>
            returns the number of rows affected by the last query when
            doing an <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT</code></a>,
            <a class="link" href="sql-syntax.html#update" title="13.2.11 UPDATE Syntax"><code class="literal">UPDATE</code></a>, or
            <a class="link" href="sql-syntax.html#delete" title="13.2.2 DELETE Syntax"><code class="literal">DELETE</code></a>.
          </p><p>
            For a fast re-create, use <a class="link" href="sql-syntax.html#truncate-table" title="13.1.34 TRUNCATE TABLE Syntax"><code class="literal">TRUNCATE
            TABLE</code></a>.
          </p></li><li class="listitem"><p>
            <a class="link" href="connectors-apis.html#mysql-num-rows" title="27.8.7.49 mysql_num_rows()"><code class="literal">mysql_num_rows()</code></a> returns the
            number of rows in a result set. With
            <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a>,
            <a class="link" href="connectors-apis.html#mysql-num-rows" title="27.8.7.49 mysql_num_rows()"><code class="literal">mysql_num_rows()</code></a> may be
            called as soon as
            <a class="link" href="connectors-apis.html#mysql-store-result" title="27.8.7.75 mysql_store_result()"><code class="literal">mysql_store_result()</code></a>
            returns. With
            <a class="link" href="connectors-apis.html#mysql-use-result" title="27.8.7.77 mysql_use_result()"><code class="literal">mysql_use_result()</code></a>,
            <a class="link" href="connectors-apis.html#mysql-num-rows" title="27.8.7.49 mysql_num_rows()"><code class="literal">mysql_num_rows()</code></a> may be
            called only after you have fetched all the rows with
            <a class="link" href="connectors-apis.html#mysql-fetch-row" title="27.8.7.21 mysql_fetch_row()"><code class="literal">mysql_fetch_row()</code></a>.
          </p></li><li class="listitem"><p>
            <a class="link" href="connectors-apis.html#mysql-insert-id" title="27.8.7.38 mysql_insert_id()"><code class="literal">mysql_insert_id()</code></a> returns
            the ID generated by the last query that inserted a row into
            a table with an <code class="literal">AUTO_INCREMENT</code> index. See
            <a class="xref" href="connectors-apis.html#mysql-insert-id" title="27.8.7.38 mysql_insert_id()">Section 27.8.7.38, “mysql_insert_id()”</a>.
          </p></li><li class="listitem"><p>
            Some queries
            (<a class="link" href="sql-syntax.html#load-data" title="13.2.6 LOAD DATA INFILE Syntax"><code class="literal">LOAD DATA INFILE
            ...</code></a>,
            <a class="link" href="sql-syntax.html#insert-select" title="13.2.5.1 INSERT ... SELECT Syntax"><code class="literal">INSERT INTO
            ... SELECT ...</code></a>,
            <a class="link" href="sql-syntax.html#update" title="13.2.11 UPDATE Syntax"><code class="literal">UPDATE</code></a>) return additional
            information. The result is returned by
            <a class="link" href="connectors-apis.html#mysql-info" title="27.8.7.36 mysql_info()"><code class="literal">mysql_info()</code></a>. See the
            description for <a class="link" href="connectors-apis.html#mysql-info" title="27.8.7.36 mysql_info()"><code class="literal">mysql_info()</code></a>
            for the format of the string that it returns.
            <a class="link" href="connectors-apis.html#mysql-info" title="27.8.7.36 mysql_info()"><code class="literal">mysql_info()</code></a> returns a
            <code class="literal">NULL</code> pointer if there is no additional
            information.
</p></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="getting-unique-id"></a>27.8.21.3 How to Get the Unique ID for the Last Inserted Row</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140710570726368"></a><a class="indexterm" name="idm140710570725328"></a><a class="indexterm" name="idm140710570724256"></a><a class="indexterm" name="idm140710570723184"></a><a class="indexterm" name="idm140710570721696"></a><a class="indexterm" name="idm140710570720240"></a><p>
        If you insert a record into a table that contains an
        <code class="literal">AUTO_INCREMENT</code> column, you can obtain the
        value stored into that column by calling the
        <a class="link" href="connectors-apis.html#mysql-insert-id" title="27.8.7.38 mysql_insert_id()"><code class="literal">mysql_insert_id()</code></a> function.
      </p><p>
        You can check from your C applications whether a value was
        stored in an <code class="literal">AUTO_INCREMENT</code> column by
        executing the following code (which assumes that you've checked
        that the statement succeeded). It determines whether the query
        was an <a class="link" href="sql-syntax.html#insert" title="13.2.5 INSERT Syntax"><code class="literal">INSERT</code></a> with an
        <code class="literal">AUTO_INCREMENT</code> index:
      </p><pre data-lang="c" class="programlisting">
if ((result = mysql_store_result(&amp;mysql)) == 0 &amp;&amp;
    mysql_field_count(&amp;mysql) == 0 &amp;&amp;
    mysql_insert_id(&amp;mysql) != 0)
{
    used_id = mysql_insert_id(&amp;mysql);
}
</pre><p>
        When a new <code class="literal">AUTO_INCREMENT</code> value has been
        generated, you can also obtain it by executing a <code class="literal">SELECT
        LAST_INSERT_ID()</code> statement with
        <a class="link" href="connectors-apis.html#mysql-query" title="27.8.7.53 mysql_query()"><code class="literal">mysql_query()</code></a> and retrieving the
        value from the result set returned by the statement.
      </p><p>
        When inserting multiple values, the last automatically
        incremented value is returned.
      </p><p>
        For <a class="link" href="functions.html#function_last-insert-id"><code class="literal">LAST_INSERT_ID()</code></a>, the most
        recently generated ID is maintained in the server on a
        per-connection basis. It is not changed by another client. It is
        not even changed if you update another
        <code class="literal">AUTO_INCREMENT</code> column with a nonmagic value
        (that is, a value that is not <code class="literal">NULL</code> and not
        <code class="literal">0</code>). Using
        <a class="link" href="functions.html#function_last-insert-id"><code class="literal">LAST_INSERT_ID()</code></a> and
        <code class="literal">AUTO_INCREMENT</code> columns simultaneously from
        multiple clients is perfectly valid. Each client will receive
        the last inserted ID for the last statement
        <span class="emphasis"><em>that</em></span> client executed.
      </p><p>
        If you want to use the ID that was generated for one table and
        insert it into a second table, you can use SQL statements like
        this:
      </p><pre data-lang="sql" class="programlisting">
INSERT INTO foo (auto,text)
    VALUES(NULL,'text');         # generate ID by inserting NULL
INSERT INTO foo2 (id,text)
    VALUES(LAST_INSERT_ID(),'text');  # use ID in second table
</pre><p>
        <a class="link" href="connectors-apis.html#mysql-insert-id" title="27.8.7.38 mysql_insert_id()"><code class="literal">mysql_insert_id()</code></a> returns the
        value stored into an <code class="literal">AUTO_INCREMENT</code> column,
        whether that value is automatically generated by storing
        <code class="literal">NULL</code> or <code class="literal">0</code> or was specified
        as an explicit value.
        <a class="link" href="functions.html#function_last-insert-id"><code class="literal">LAST_INSERT_ID()</code></a> returns only
        automatically generated <code class="literal">AUTO_INCREMENT</code>
        values. If you store an explicit value other than
        <code class="literal">NULL</code> or <code class="literal">0</code>, it does not
        affect the value returned by
        <a class="link" href="functions.html#function_last-insert-id"><code class="literal">LAST_INSERT_ID()</code></a>.
      </p><p>
        For more information on obtaining the last ID in an
        <code class="literal">AUTO_INCREMENT</code> column:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            For information on
            <a class="link" href="functions.html#function_last-insert-id"><code class="literal">LAST_INSERT_ID()</code></a>, which can
            be used within an SQL statement, see
            <a class="xref" href="functions.html#information-functions" title="12.14 Information Functions">Section 12.14, “Information Functions”</a>.
          </p></li><li class="listitem"><p>
            For information on
            <a class="link" href="connectors-apis.html#mysql-insert-id" title="27.8.7.38 mysql_insert_id()"><code class="literal">mysql_insert_id()</code></a>, the
            function you use from within the C API, see
            <a class="xref" href="connectors-apis.html#mysql-insert-id" title="27.8.7.38 mysql_insert_id()">Section 27.8.7.38, “mysql_insert_id()”</a>.
          </p></li><li class="listitem"><p>
            For information on obtaining the auto-incremented value when
            using Connector/J, see
            <a class="ulink" href="http://dev.mysql.com/doc/connector-j/5.1/en/connector-j-usagenotes-last-insert-id.html" target="_top">Retrieving <code class="literal">AUTO_INCREMENT</code> Column Values through JDBC</a>.
          </p></li><li class="listitem"><p>
            For information on obtaining the auto-incremented value when
            using Connector/ODBC, see
            <a class="ulink" href="http://dev.mysql.com/doc/connector-odbc/en/connector-odbc-usagenotes-functionality-last-insert-id.html" target="_top">Obtaining Auto-Increment Values</a>.
</p></li></ul>
</div>

</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="apis-php-info"></a>27.9 MySQL PHP API</h2>

</div>

</div>

</div>
<p>
    The MySQL PHP API manual is now published in standalone form, not as
    part of the MySQL Reference Manual. See <a class="ulink" href="http://dev.mysql.com/doc/apis-php/en/" target="_top">MySQL and PHP</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="apis-perl"></a>27.10 MySQL Perl API</h2>

</div>

</div>

</div>
<a class="indexterm" name="idm140710570675392"></a><a class="indexterm" name="idm140710570673936"></a><a class="indexterm" name="idm140710570672864"></a><a class="indexterm" name="idm140710570671792"></a><p>
    The Perl <code class="literal">DBI</code> module provides a generic interface
    for database access. You can write a DBI script that works with many
    different database engines without change. To use DBI with MySQL,
    install the following:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
        The <code class="literal">DBI</code> module.
      </p></li><li class="listitem"><p>
        The <code class="literal">DBD::mysql</code> module. This is the DataBase
        Driver (DBD) module for Perl.
      </p></li><li class="listitem"><p>
        Optionally, the DBD module for any other type of database server
        you want to access.
</p></li></ol>
</div>
<p>
    Perl DBI is the recommended Perl interface. It replaces an older
    interface called <code class="literal">mysqlperl</code>, which should be
    considered obsolete.
  </p><p>
    These sections contain information about using Perl with MySQL and
    writing MySQL applications in Perl:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
        For installation instructions for Perl DBI support, see
        <a class="xref" href="installing.html#perl-support" title="2.12 Perl Installation Notes">Section 2.12, “Perl Installation Notes”</a>.
      </p></li><li class="listitem"><p>
        For an example of reading options from option files, see
        <a class="xref" href="server-administration.html#multiple-server-clients" title="5.6.4 Using Client Programs in a Multiple-Server Environment">Section 5.6.4, “Using Client Programs in a Multiple-Server Environment”</a>.
      </p></li><li class="listitem"><p>
        For secure coding tips, see
        <a class="xref" href="security.html#security-guidelines" title="6.1.1 Security Guidelines">Section 6.1.1, “Security Guidelines”</a>.
      </p></li><li class="listitem"><p>
        For debugging tips, see <a class="xref" href="extending-mysql.html#using-gdb-on-mysqld" title="28.5.1.4 Debugging mysqld under gdb">Section 28.5.1.4, “Debugging mysqld under gdb”</a>.
      </p></li><li class="listitem"><p>
        For some Perl-specific environment variables, see
        <a class="xref" href="programs.html#environment-variables" title="4.9 MySQL Program Environment Variables">Section 4.9, “MySQL Program Environment Variables”</a>.
      </p></li><li class="listitem"><p>
        For considerations for running on OS X, see
        <a class="xref" href="installing.html#osx-installation" title="2.4 Installing MySQL on macOS">Section 2.4, “Installing MySQL on macOS”</a>.
      </p></li><li class="listitem"><p>
        For ways to quote string literals, see
        <a class="xref" href="language-structure.html#string-literals" title="9.1.1 String Literals">Section 9.1.1, “String Literals”</a>.
</p></li></ul>
</div>
<p>
    DBI information is available at the command line, online, or in
    printed form:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
        Once you have the <code class="literal">DBI</code> and
        <code class="literal">DBD::mysql</code> modules installed, you can get
        information about them at the command line with the
        <code class="literal">perldoc</code> command:
      </p><pre class="programlisting">
shell&gt; <strong class="userinput"><code>perldoc DBI</code></strong>
shell&gt; <strong class="userinput"><code>perldoc DBI::FAQ</code></strong>
shell&gt; <strong class="userinput"><code>perldoc DBD::mysql</code></strong>
</pre><p>
        You can also use <code class="literal">pod2man</code>,
        <code class="literal">pod2html</code>, and so on to translate this
        information into other formats.
      </p></li><li class="listitem"><p>
        For online information about Perl DBI, visit the DBI website,
        <a class="ulink" href="http://dbi.perl.org/" target="_top">http://dbi.perl.org/</a>. That site hosts a general
        DBI mailing list. Oracle Corporation hosts a list specifically
        about <code class="literal">DBD::mysql</code>; see
        <a class="xref" href="introduction.html#mailing-lists" title="1.6.2 MySQL Mailing Lists">Section 1.6.2, “MySQL Mailing Lists”</a>.
      </p></li><li class="listitem"><p>
        For printed information, the official DBI book is
        <em class="citetitle">Programming the Perl DBI</em> (Alligator
        Descartes and Tim Bunce, O'Reilly &amp; Associates, 2000).
        Information about the book is available at the DBI website,
        <a class="ulink" href="http://dbi.perl.org/" target="_top">http://dbi.perl.org/</a>.
</p></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="apis-python"></a>27.11 MySQL Python API</h2>

</div>

</div>

</div>
<a class="indexterm" name="idm140710570635408"></a><p>
    <code class="literal">MySQLdb</code> is a third-party driver that provides
    MySQL support for Python, compliant with the Python DB API version
    2.0. It can be found at
    <a class="ulink" href="http://sourceforge.net/projects/mysql-python/" target="_top">http://sourceforge.net/projects/mysql-python/</a>.
  </p><p>
    The new MySQL Connector/Python component provides an interface to
    the same Python API, and is built into the MySQL Server and
    supported by Oracle. See <a class="ulink" href="http://dev.mysql.com/doc/connector-python/en/" target="_top">MySQL Connector/Python Developer Guide</a> for
    details on the Connector, as well as coding guidelines for Python
    applications and sample Python code.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="apis-ruby"></a>27.12 MySQL Ruby APIs</h2>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="connectors-apis.html#apis-ruby-mysqlruby">27.12.1 The MySQL/Ruby API</a></span></dt><dt><span class="section"><a href="connectors-apis.html#apis-ruby-rubymysql">27.12.2 The Ruby/MySQL API</a></span></dt></dl>
</div>
<a class="indexterm" name="idm140710570629104"></a><p>
    Two APIs are available for Ruby programmers developing MySQL
    applications:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
        The MySQL/Ruby API is based on the
        <code class="literal">libmysqlclient</code> API library. For information
        on installing and using the MySQL/Ruby API, see
        <a class="xref" href="connectors-apis.html#apis-ruby-mysqlruby" title="27.12.1 The MySQL/Ruby API">Section 27.12.1, “The MySQL/Ruby API”</a>.
      </p></li><li class="listitem"><p>
        The Ruby/MySQL API is written to use the native MySQL network
        protocol (a native driver). For information on installing and
        using the Ruby/MySQL API, see
        <a class="xref" href="connectors-apis.html#apis-ruby-rubymysql" title="27.12.2 The Ruby/MySQL API">Section 27.12.2, “The Ruby/MySQL API”</a>.
</p></li></ul>
</div>
<p>
    For background and syntax information about the Ruby language, see
    <a class="ulink" href="http://www.ruby-lang.org" target="_top">Ruby Programming
    Language</a>.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="apis-ruby-mysqlruby"></a>27.12.1 The MySQL/Ruby API</h3>
</div>
</div>
</div>
<p>
      The MySQL/Ruby module provides access to MySQL databases using
      Ruby through <code class="literal">libmysqlclient</code>.
    </p><p>
      For information on installing the module, and the functions
      exposed, see
      <a class="ulink" href="http://tmtm.org/en/mysql/ruby/" target="_top">MySQL/Ruby</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="apis-ruby-rubymysql"></a>27.12.2 The Ruby/MySQL API</h3>

</div>

</div>

</div>
<p>
      The Ruby/MySQL module provides access to MySQL databases using
      Ruby through a native driver interface using the MySQL network
      protocol.
    </p><p>
      For information on installing the module, and the functions
      exposed, see
      <a class="ulink" href="http://tmtm.org/en/ruby/mysql/README_en.html" target="_top">Ruby/MySQL</a>.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="apis-tcl"></a>27.13 MySQL Tcl API</h2>

</div>

</div>

</div>
<a class="indexterm" name="idm140710570613872"></a><p>
    <code class="literal">MySQLtcl</code> is a simple API for accessing a MySQL
    database server from the
    <a class="ulink" href="http://en.wikipedia.org/wiki/Tcl" target="_top">Tcl programming
    language</a>. It can be found at
    <a class="ulink" href="http://www.xdobry.de/mysqltcl/" target="_top">http://www.xdobry.de/mysqltcl/</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="apis-eiffel"></a>27.14 MySQL Eiffel Wrapper</h2>

</div>

</div>

</div>
<a class="indexterm" name="idm140710570608832"></a><a class="indexterm" name="idm140710570607792"></a><p>
    Eiffel MySQL is an interface to the MySQL database server using the
    <a class="ulink" href="http://en.wikipedia.org/wiki/Eiffel_(programming_language)" target="_top">Eiffel
    programming language</a>, written by Michael Ravits. It can be
    found at
    <a class="ulink" href="http://efsa.sourceforge.net/archive/ravits/mysql.htm" target="_top">http://efsa.sourceforge.net/archive/ravits/mysql.htm</a>.
</p>
</div>

</div>
<div class="copyright-footer">

</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="sys-schema.html">Prev</a></td>
<td width="20%" align="center"><a accesskey="u" href="">Up</a></td>
<td width="40%" align="right"> <a accesskey="n" href="extending-mysql.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 26 MySQL sys Schema</td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top">Chapter 28 Extending MySQL</td>
</tr>
</table>
</div>
</body>
</html>
